Internationalization

Internationalization (i18n)

Typically, components allow users to supply text values via slots and attributes, but there are cases where components need to take additional steps to support internationalization.

Formatting

Formatting of values, such as numbers and dates, for display should use the Intl APIs.

Styling/Layout

To add right-to-left (RTL) support to your components you should use CSS Logical properties within CSS. If you need to know direction in JavaScript, use the internal getElementDir helper in the dom utility.

Some CSS properties do not have logical equivalents. Such as...

• box-shadow
• text-shadow
• transform
• background-position

For these properties, you should use the internal getElementDir helper to apply the CSS_UTILITY.rtl class to your component.

Translation (t9n)

The following section covers how to add built-in translation support to components.

useT9nController pattern

This pattern enables components to support built-in translations. In order to support this, a component must:

1. Implement the useT9nController. Refer to useT9n doc for implementation specifications.
2. Add the translation bundles as described in the documentation.
3. Add an appropriate E2E test by using the t9n common test helper.
4. For internal components that support public t9n components
   1. Do not implement the useT9n controller
   2. Use an internal messages property and its type should correspond to the parent component's messages type as described here.
5. Refer to the Calcite Translation Build Process for a comprehensive guide to implementing built-in translation.

Notes

• The internal messages property should be used as the source of truth for translations during rendering.
• List of supported locales can be found on our Localization support page.
• Placeholders in message bundle strings should:
  • Use the following syntax: {placeholder} (e.g., Hello {userName}, my old friend. 👋).
  • Have expressive name to provide context regarding its use.
• All Pull Requests related to t9n in Calcite Design System should follow commit message format.