Skip to main content

Internationalization Implementation

  • Status: Proposed
  • Author: Michael White
  • Deciders: Abyss Team
  • Date: 07/17/2024

Context​

For both the Abyss Mobile and Abyss Web libraries, there are hardcoded text values that cannot be updated by consuming teams. This is a problem because consuming teams have asked for the ability to override the text in our components, whether it's to override a single text block or translate all of the text to a different language.

Decision​

The decision is to create an I18nProvider, a provider component that accepts a translations prop to override the text used in Abyss components. The context will provide two properties:

  • (t) A translation function to fetch the exact value.
  • (i18n) An object that displays the full translation mapping

Internally, we will use a useTranslate hook which will provide a t function that takes in a dotted string (eg. 'TextField.charactersRemaining'), and returns the matching string for that value. useTranslate will also have access to the i18n object. Consuming teams will also have access to useTranslate in the event that they want to look up values as well.

const Component = () => {
  const { t, i18n } = useTranslate();
  return <span>{t('Alert.closeAlert')}</span>;
};

In addition, a Translate component will be available for consuming teams who are using class-based components or prefer grabbing the translation context from a component as opposed to a hook. The children prop will accept a function with the translations context as a parameter.

const Component = () => {
  return (
    <Translate>
      {({ t, i18n }) => {
        return <Text>{t('Alert.closeAlert')}</Text>;
      }}
    </Translate>
  );
};

The map of values that can be overridden will have:

  • A set of common words that are used within multiple components.
  • Words that are scoped to an individual component.
const en = {
  alert: 'Alert',
  back: 'Back',
  cancel: 'Cancel',
  close: 'Close',
  disabled: 'Disabled',
  help: 'Help',
  loading: 'loading',
  Accumulator: {
    percentage: '{{percentage}} percent',
  },
  Alert: {
    closeAlert: 'Close Alert',
  },
};

In the event that a string needs to have variables, a string can be placed inside of double curly braces, and the translation function, t, will parse the value within the string itself.

const Component = () => {
  const { t, i18n } = useTranslate();
  return <span>{t('Accumulator.percentage', { percentage: 10 })}</span>;
};

Consequences​

Pros​

  1. Consuming teams will be able to override default Abyss text values to either manipulate our English text, or add translations for other languages.

  2. Will allow consuming teams to create their own I18n solutions for their applications.

Cons​

  1. Abyss will have to manage a manual list of english translations.

Alternatives Considered​

  1. Manage translations for multiple translations internally.

Future Considerations​

  • Consolidating all text into one file would eventually allow us, if we so chose, to externalize that file, say in a Lagoon table, thus allowing business owners or designers to alter the text without any code changes.

References​

Revision History​

  • 07/17/2024: Initial draft
Table of Contents