Translate your application strings to different languages

Translate your application in three steps:

1. Declare the list of locales your application supports.
2. Replace hard-coded strings with translation keys.
3. Provide a translation for each supported locale.

Copy link to this section

Declare backend locales

Declare which locales your application supports by seeding Locale in your application package. Use either {package}/seed/Locale/{file}.json or {package}/seed/Locale/{file}.csv.

As an example:

// {package}/seed/Locale/locales.json
[
  {
    "id": "en",
    "language": "en",
    "name": "English"
  },
  {
    "id": "en_AU",
    "language": "en",
    "region": "AU",
    "name": "English (Australia)"
  },
  {
    "id": "es",
    "language": "es",
    "name": "Spanish"
  },
  {
    "id": "es_MX",
    "language": "es",
    "region": "MX",
    "name": "Spanish (Mexico)"
  }
]

Copy link to this section

Declare frontend locales

Declare the same list of locales in the frontend of the application by adding them to {package}/config/UiSdlConfig/{file}.json. Ensure the locale IDs match those in the backend.

As an example:

// {package}/config/UiSdlConfig/default.json
{
  "i18n": {
    "locales": [
      {
        "id": "en"
      },
      {
        "id": "en_AU"
      },
      {
        "id": "es"
      },
      {
        "id": "es_MX"
      }
    ]
  }
  // Other default configurations as needed, like application theme
}

The first element in this array will be used as the default language of your application, when the end-user does not specify a locale preference.

Copy link to this section

Replace hard-coded strings

Find all hard-coded strings in your application and replace them by a translation key, ensuring your application is language-agnostic.

As an example, if you have an application to manage windturbines, instead of hard-coding the string "windturbine" in your application:

• Replace that hard-coded string with a unique key
• For each of the locales you support, create a separate CSV file to map that unique translation key.

The best practice for the unique translation key is to follow the pattern {package}.{intent}. This makes it easier to find what is the package where that string is found and the intent behind it, making it easier to work with translation services, refactoring, and troubleshooting.

As an example, let's say you have the following button instance where the word "windturbine" is hard-coded:

{
  "type" : "UiSdlConnected<UiSdlButton>",
  "component" : {
    // Hardcoded string value
    "content" : "Windturbine"
  }
}

We would replace the string by a unique translation identifier:

{
  "type" : "UiSdlConnected<UiSdlButton>",
  "component" : {
    // Unique translation id, the concrete string at runtime
    // Will depend on the user's locale preference
    "content" : "myPackage.windturbine.label"
  }
}

Copy link to this section

Provide translation files

For each of the supported locales, create a Translation CSV file to map the unique translation identifier to the actual string to display in each locale.

The best practice is to create a separate CSV file for each locale.

id,locale,key,value
en.myPackage.windturbine.label,en,myPackage.windturbine.label,Call elevator

Copy link to this section

Translating a full application

The best practice is to never use hard-coded strings in your application package, and always start with a single default translation file. This allows team members to reuse translation identifiers, and also minimizes the cost of introducing support for a new language.

Assuming all the strings in your application are already using a unique translation identifier, to introduce support for a new language:

1. Get all translation keys
2. Provide a translation for them

Copy link to this section

Get all translation keys

The best way to get all unique translation keys for your application is to start the application and from a notebook or console run:

Translation.fetch({include: 'key', order: 'key'})

This ensures you have visibility into all unique translation keys that exist in all packages that make up your application.

Copy link to this section

Provide a translation

Once you know all unique translation keys your application packages are using, you can introduce support for a new locale by declaring a new locale and providing a new translation CSV for that locale.