RFC: Internationalization

[lucasaarcoverde]

Problem

In the design system, we have internal translations to help our users by previously defining common messages in different apps and letting them use the messages.

The main issue is that we created a pattern to reuse the i18n behavior along the projects, but this is still experimental, and the way of adding, removing, and updating messages is not scalable.

Why this matters?

• Internal translations can guarantee message consistency throughout different apps.
• Many projects don’t set up the i18n, and the messages are always set to English.
• Adding new translations is manual, so it’s not scalable.
• The localization team is blind regarding the state of our translations

Proposal

IMO there are two problems to be solved by this RFC, which are:

• The localization team should be able to control the evolution/state of our internal translations
• The setup of the i18n should be mandatory and easy to do.

App set up proposal

Before

import { useRuntime } from 'vtex.render-runtime'
import { I18nProvider, ThemeProvider } from '@vtex/admin-ui'

export function Example() {
  const { culture: { locale } } = useRuntime()
  
  return (
    <ThemeProvider>
      <I18nProvider locale={locale}>
        {/** your app goes here */}
      </I18nProvider>
    <ThemeProvider>
  )
}

After

import { useRuntime } from 'vtex.render-runtime'
// SystemProvider or AdminUIProvider makes more sense in this case, but I think this should be in another RFC
import { ThemeProvider } from '@vtex/admin-ui'

export function Example() {
  const { culture: { locale } } = useRuntime()
  
  return (
	  // locale property is mandatory in this case
    <ThemeProvider locale={locale}>
        {/** your app goes here */}
    <ThemeProvider>
  )
}

Messages evolution proposal

Two issues make it harder for the localization team to maintain those translations:

1. There are several message files, and they are specific to a single component. This leaves the localization team with no control over what is being updated or where they should add new translations.
2. Every language translation is in the same file, which is a different structure from the one supported by the crowdin, and this makes the team have to manually open PRs in the project instead of using the translation tool.

Before

// admin-ui root
- packages
|-- admin-ui
  |-- src
    |-- component
      |-- component.i18n.ts

After

// admin-ui root
- crowdin.yml
- packages
|-- admin-ui
  |-- src
  |-- messages
    |-- en.json
    |-- pt.json
    ...

// crowdin.yml file
files:
  - source: /packages/admin-ui/messages/en.json
    translation: /%original_path%/%two_letters_code%.%file_extension%

Pros

• We won’t have apps without setting up the i18n since now is mandatory
• The localization team will be able to help us proactively instead of reactive
• Easier to fully set up the admin-ui

Cons

• A ThemeProvider component with a locale property doesn’t make much sense, we’ll probably need to change it which will cause a breaking change.
• The messages are not attached to a component anymore. I don’t see it as a big deal, but is something that we’ll need to get used to

Unresolved questions

• Should we change the ThemeProvider to something different? What do you think of creating an RFC about it?

What's next

• Hear feedback and discuss this solution.
• Apply changes to the code and documentation

[anitavincent]

Maybe we can think about a way of separating the messages in a file by component so it doesn't become messy... Since it's a json I don't know if there's much we can do other than adding blank lines between groups or something

A problem that happens a lot in apps in this model is that stale messages end up never getting deleted and it's a little hard to find what messages are not being used anymore. The file ends up growing "forever"

[lucasaarcoverde]

I agree! I said I don't see this as a big deal because we only have ~26 translations now, and I don't see it growing much more. We can still do it separated by component, and the only con I can see is that we would need to have one file path configured in the Crowdin file for each component, but maybe this is easier than maintaining a huge JSON file.

[lucasaarcoverde]

An alternative for having a single messages folder is to have one folder for each component, we just need to change the Crowdin file if we want that away.

// admin-ui root
- crowdin.yml
- packages
|-- admin-ui
  |-- src
    |-- Search
      |-- messages
        |-- en.json
        |-- pt.json
        ...
    |-- Filter
      |-- messages
        |-- en.json
        |-- pt.json
        ...

// crowdin.yml file
files:
  - source: /packages/admin-ui/src/search/messages/en.json
    translation: /%original_path%/%two_letters_code%.%file_extension%
  - source: /packages/admin-ui/src/filter/messages/en.json
    translation: /%original_path%/%two_letters_code%.%file_extension%
...

Pros

• As @anitavincent said when we have several messages the files grow a lot and become really hard to maintain clean, this way we have small files specific for the context where they are being used, so it's easier to maintain.

Cons

• Now we need to maintain the Crowdin file updated every time we have a new component translation or when we remove it.

Unresolved questions

• @camilavcoutinho is that ok to have multiple sources in the crowdin.yml or it brings complexity to add/edit/remove translations?

[camilavcoutinho]

Unresolved questions

• @camilavcoutinho is that ok to have multiple sources in the crowdin.yml or it brings complexity to add/edit/remove translations?

No problem! We only need to make sure that all the sources are updated in crowdin configuration file.

[lucasaarcoverde]

For me, we can go with this solution then!

[matheusps]

Implemented