🚀 Internationalization (i18n) Translations [Meta Issue]

[awanlin]

Description

Now that we have initial support for Internationalization (i18n) we need to start working on getting translations in place. This issue will act as a meta issue to help track the work on this

Links

Documentation: https://backstage.io/docs/plugins/internationalization/ Initial PR: https://github.com/backstage/backstage/pull/17436

Usage examples:

• https://github.com/backstage/backstage/pull/19786

[awanlin]

There is also this PR that is being worked on: https://github.com/backstage/backstage/pull/20130

[Rugvip]

One things that we haven't figured out yet is the message key design guidelines. We're using snake_case, but I think there's some discussion to be had around how we want to nest things and how specific we want to get vs avoiding duplication. Any suggestions for existing standards to adopt would be welcome! 🙏

[gashcrumb]

I've been recently starting to follow this effort and would love to help out here as well. I've used react-i18next on a couple projects and found their best practices and the overall principals section of their documentation really helpful.

For example, using the key as a fallback is something to consider, as otherwise if the i18n layer can't load it's translation, the user could be left with difficult to understand text in the UI.

I guess another thing to look at is what formats do translation services like to receive? Those would also be a good starting point.

[angeliski]

Moving my comments to here:

1. Should a Plugin be full moved to I18N before first merge?

I started to move some strings from components and... OMG threre is a lot of words here 😅 So my first suggestion is to be clear about this: We want all or nothing?

Suggestion: I prefer not wait for the full translation, so we can wave small PRs

2. Flat keys vs Deep Keys

I started to translate looking using the User Settings as reference. But this plugin, like many others have so many components I got a little confused about to stay flat.

Juts to get context, we have two options here:

{
    "component_name": "My Component",
    "component": {
        "name": "My Component"
    }
}

t('component_name') 
t('component.name')

I stayed using flat keys, but after walk a little in the translation ref I got some doubts. Flat keys will provide a simple way to reuse words and phrases, but can get a little messy. Deep keys could provide a more organized approach, but we can got a big file because of that.

Suggestion: Stay flat and things got messy we can refactor and provide a migration path (maybe a tool too)

3. Semantic Keys vs Plain text keys

We have a lot of work to change those hard coded words. So I started to use this plugin to help me. It's really fast extract the word to a json and after that put in TS. But the fast way to do that is using a approach more "your key is your text", like here. We can use more semantic text like here too, it's just more slow because we need to get context and understand a little about the component.

Suggestion: Stay using plain text keys for most cases and when some is really specific change the approach (like here)

4. Provide a No-React way to access the I18N instance

We have some cases where text is outside a component (like here) so we need to put a way to grab the I18N instance so we can call the translate method.

Suggestion: Maybe I am missing how to do that, we can provide a doc or maybe put this in a singleton so we can grab that in a simple import

5. Be explicit about the Non Translate out-of-box

I was trying to find new languages in the project when I see we don't have a standard way to do that. I can translate may Backstage instance to Portuguese, but just in my code. Could be nice if we give some pointers about next steps about that so we don't get people frustated or expecting to contribuite for a thing and got another.

Suggestion: Create a issue with the next steps (and missing points) about the current i18n state in Backstage

[Rugvip]

Created #21267 as a separate issue to track the establishment of patterns and usages of i18n message keys. Also highlighting that we want to establish these patterns before merging any more PRs

[mattemoore]

Willing to help test and contribute to initial implementation of Catalog plugin i18n as we have a hard requirement at my department that all apps must be available in both official languages. @christopherparent

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[mattemoore]

@awanlin we are ready to start work on this. Is there any documentation or similar that we can use to get started?

[mattemoore]

@awanlin @Rugvip Sorry, I should have been more specific. I see how some components in user-settings plugin (language and theme toggles) are plumbed for localizations. I am more than happy to continue to plumb the rest of user-settings as well as other catalog components.

Does this work for you?

[awanlin]

@mattemoore, that works for me, make sure you check for any open PRs. I know that @mario-mui has been actively working on this as well: https://github.com/backstage/backstage/pulls?q=is%3Apr+author%3Amario-mui+

[mattemoore]

@awanlin I've brought this up to legal to make sure they are ok with our department contributing under the Apache2. License. Looks like @mario-mui has done a ton of work on the catalog already. Perhaps it would be more expedient for us to help test those changes?

[awanlin]

Sure, what ever you can do to help is appreciated @mattemoore! I'll note that other core features like Search, TechDocs, and Kubernetes haven't been touched yet. I think maybe Software Templates has but not 100% sure 🤔