Refactor getDocsLink in favor of getLocalizedLink

[sejas]

Related issues

• Fixes STU-470

Proposed Changes

• Unify the getBlogLink and translateLink functions that translate links into a single, easy-to-use function called getLocalizedLink, maintain a dictionary for centralized link usage, and preserve the essence suggested in Translate what's new links #1368 (comment)

Testing Instructions

• Run npm start
• Confirm the links in what's new are still working. You can follow the tests on Translate what's new links #1368
• Confirm the links pointing to the docs are still working in English, and Spanish.
  • Sections: 'system menu', 'content-tab-import-export', 'site-form', 'sync-connected-sites', and 'top-bar'

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[gcsecsey]

Thanks for making this follow-up @sejas! 🙌

The refactor looks good to me and works well. I can still open the Spanish blog post from the What's New section using this branch.

CleanShot.2025-05-12.at.15.41.05.mp4

[wojtekn]

Following the single responsibility principle, and considering that the two implementations differ significantly, I think it would make sense to have two separate files, one for getDocsLink and another for getBlogLink. Alternatively, have getDocsLink which dynamically changes the language, and another one, e.g. getLink that uses the mapping array.

[sejas]

Good point. So I opted to share the same logic and architecture. Now the translatable links use a dict/object. Types force to have the english link as a type requirement. We only have a unique function to "translate" links, which I think is important for consistency.

[sejas]

@wojtekn , thanks for the feedback. I really appreciate it. Now the code it's cleaner. We are forced to add all the links into the translation array. The sam function getLink can be used to generate docs and blog links, and potentially any kind of links.

Let me know what you think.

[sejas]

Having the full links makes it easier to test whether they work or return a 404.

[sejas]

These types force the link keys to start with blog and docs, respectively.

[wojtekn]

One last nit on method signature - if we want to enforce a prefix, would it be clearer to change the method signature and add another parameter for that?

 getLink( 'en', 'docs', 'importExport' )

Alternatively, what if we skipped enforcing that, and used one array for both docs and blog links, making it generic and not tied to the resource type it stores?

const LINKS = {
	blogPhpVersions: {
		[...]
	},
	docsPhpVersions: {
		[...]
	},
	dotOrgBlogGutenber: {
		[...]
	},
}

[sejas]

I prefer having everything in the same object. I'm not sure if forcing a prefix is useful, but I see that it can help with decision-making when seeing the autocomplete while calling the function.

I'll leave it as it is for now. We can always merge the objects and remove the prefix check later.

[wojtekn]

Sounds good, thanks for sharing this use case.

[fredrikekelund]

Nice improvement 👍 Left some minor suggestions.

[wojtekn]

Looks good, thanks for simplifying that!

[wojtekn]

One last nit on method signature - if we want to enforce a prefix, would it be clearer to change the method signature and add another parameter for that?

 getLink( 'en', 'docs', 'importExport' )

Alternatively, what if we skipped enforcing that, and used one array for both docs and blog links, making it generic and not tied to the resource type it stores?

const LINKS = {
	blogPhpVersions: {
		[...]
	},
	docsPhpVersions: {
		[...]
	},
	dotOrgBlogGutenber: {
		[...]
	},
}

[nightnei]

LGTM and works well 👍
TIL satisfies