Internationalization (i18n) in Mirador 4

Mirador's user facing text is internationalized using react-18next. There are translation.json files for each supported locale in the locales directory.

Overriding i18n keys

An implementer may override text in an existing, configured language via the config. For example, the menu option text, "Download / export settings", can be replaced with the text "gimme".

translations: {
    en: { downloadExportWorkspace: 'gimme' }
  },

Adding a new language

1. Create a directory with the locale code for the language you're adding in the locales directory.
2. Create a translation.json file in the newly created directory.
3. Translate all the keys found in an existing language's translation.json file.
4. Import your translation.json file in the i18n.js file and add it to the resources object under the appropriate locale.

Internationalizing a component

There are several different ways to internationalize a component (Hook, HOC, Render Prop, etc) that you can choose to best fit your needs and the kind of component you're working with. The react-18next documentation has detailed information on all of these scenarios, but we'll document some of our most common usage here.

useTranslation Hook

1. import the hook

   For Mirador core developers:

   import { useTranslation } from 'react-i18next';
   

   For downstream implementers and plugin developers

   import { useTranslation } from 'mirador';
   

   Mirador Core re-exports the useTranslation hook from the react-i18next for downstream consumers. See also Creating a Mirador 4 plugin

2. get the {t}

     const { t } = useTranslation();
   

3. use the {t}

    <CollapsibleSection
         id={`${id}-currentItem-${index}`}
         label={t('currentItem', { context: `${index + 1}/${totalSize}` })}
    >
   

This example is taken from the CanvasInfo component; you can view the code here. All of our components with translatable text use this same pattern.

Required vs. default t prop

As of writing this, the pattern we're using here is fluid. It'll be best to look at what the established pattern in the code is and try to use that.

Guiding principles for i18n keys and user facing strings

• All user facing text must be internationalized (screen-reader only text, relevant aria attributes, etc. included)
• Keys should be camelCase
• Keys should be alphabetized in the translation.json file