C3 AI Documentation Home

Localization in the C3 AI UI Framework

Localization overview

Localization plays an important role in making an application available to a global audience because people all over the world speak and read different languages and understand different date and number formatting.

The C3 AI UI Framework supports a number of localization features. The relevant Types are:

  • Locale
    • A locale identifies a region (such as a country) in which people speak a particular language or language variant. The locale determines the formatting and parsing of dates, times, numbers, and currencies as well as measurement units and the translated names for time zones, languages, and countries.
  • UiSdlI18nConfig
    • A Config Type for specifying the list of locales that an application supports. This config Type is a ChildConfig of UiSdlConfig.
  • UiSdlUserPreference
  • Translation
    • A translation indicates a single message catered to a specific locale. A translation set can have multiple translations for the same Translation#key, one for each locale.

Locale

The Locale#id should be a valid POSIX/C locale. For example:

  • en: English (International)
  • en_US: American English
  • en_GB: British English
  • fr: French
  • sr_ME: Serbian (Cyrillic script, Montenegro)
  • sr_ME@latin: Serbian (Latin script, Montenegro)
  • uz_UZ@cyrillic: Uzbek (Cyrillic script, Uzbekistan)

See GNU – Locale Names for more information.

UiSdlI18nConfig

UiSdlI18nConfig contains the list of available locales, or in other words, the locales that an application supports. The first locale is the default locale for locale negotiation purposes.

UiSdlConfig is the parent config type to UiSdlI18nConfig. See Config for more information regarding seeding this config in an application package.

UiSdlUserPreference

UiSdlUserPreference contains the preferences for a single user of the UI application. When the user has specified a UiSdlUserPreference#preferredLocale, the C3 AI UI Framework uses this locale as the highest priority during locale negotiation.

Locale negotiation

When a user visits the UI application, a locale negotiation process determines which locale to use for displaying the application to the user.

Given a list of available locales specified by UiSdlI18nConfig.locales, the C3 AI UI Framework takes into account the following locales, in order:

  1. UiSdlUserPreference.preferredLocale.
  2. The web browser's preferred locales (see Navigator.languages and Navigator.language).
  3. The application default locale, the first locale in UiSdlI18nConfig.locales.
  4. The global default locale (en).

Once one of the locales is chosen, the C3 AI UI Framework uses that locale for all messaging, number and date formatting, and data requests wherever possible.

Translation

As noted in Localization and Translation, by convention, the id of a Translation is its locale and key joined by a period: locale.key. The key is a identifier for a message that can be translated into multiple languages.

By convention, the key for UI Translation metadata indicates to which component the Translation applies and its usage within the component, and so the key is structured Component ID.Path to Usage.

Providing translation metadata

The Translation metadata goes in Translation seed files. For example, myApp/seed/Translation/en.csv would have

CSV
id,locale,key,value
en.myApp.MyModal.header.text,en,myApp.MyModal.header.text,Enter your detailed text

and myApp/seed/Translation/fr.csv would then have

CSV
id,locale,key,value
fr.myApp.MyModal.header.text,fr,myApp.MyModal.header.text,Entrez votre texte détaillé

While the Translation seed data can follow any file structure you'd like, providing one Translation seed file per locale is a good starting point. This approach makes it simple to extract your application's Translation set and distribute it to an external translation service for translating into other languages.

Translation inheritance

UI translation bundles inherit translations from their parent locales. As a result, an app that supports both English (United States) and English (United Kingdom) does not need to provide copies of every Translation for both the en_US and en_GB locales.

Best practice is for app developers to provide translations at the "lowest level" as is reasonable for the given translation content. For example, most English translations should go in the base language en (English) locale, and only translations which require region-specific spelling or phrasing should go in the region-specific locales (for example en_GB or en_001).

Note that computing the parent locale of a given locale is not as simple as truncating its region. For information regarding parent locales, see Locale#computedParent.

Using translations in UI components

In order to use the Translation in the UI, the UI component references the Translation.key. For example, myApp/ui/c3/meta/myApp.MyModal.json would have

JSON
{
  "type": "UiSdlConnected<UiSdlModal>",
  "component": {
    "header": {
      "text": "myApp.MyModal.header.text"
    }
  }
}

In this example for displaying text in a modal header, the C3 AI UI Framework uses the Translation.value that corresponds to the Translation whose id matches the application's current locale and whose key is myApp.MyModal.header.text.

Advanced translations and other dynamic text

For more advanced translations, as well as localized number and date formatting, see UiSdlDynamicValueSpec.

Testing with pseudolocales

The C3 AI UI Framework supports two pseudolocales to assist in validating an application's internationalization support:

  • en_XA: English (Pseudo-Accents)
    • Replaces most ASCII characters with Unicode characters containing accents and other diacritic marks.
    • Useful for identifying text which is not using localized formatting and/or Translations.
  • ar_XB: Arabic (Pseudo-Bidi)
    • Replaces ASCII letters with "upside-down" letters and inserts bidirectional text markers around text.
    • Useful for identifying styling and other formatting issues when displaying RTL (Right-to-Left) scripts such as Arabic and Hebrew.

To enable these pseudolocales, add them to the application's UiSdlI18nConfig.locales, and optionally set the user's UiSdlUserPreference.preferredLocale accordingly.

Current limitations for pseudolocales

At this time, only UI translations are automatically generated for pseudolocales. To include data translations as well, create the appropriate Translation seed data and include it in the application package.

Was this page helpful?