Skip to main content

Using Translations Within a Project

This page describes how the localization system is implemented inside applications using it.

react-i18-next​

react-i18next is a library that provides internationalization (i18next) and localization (l10n) support for React applications. It is used in project to translate the text content in the user interface. For more information check out the official react-i18-next documentation.

Configuration​

The i18next.config.js file is used to configure the i18next internationalization library in a project, defining settings like supported languages, default language, and translation file paths. It centralizes and exports these options so i18next can initialize consistently across the app.

The configuration for most ABAIR projects is basic. The only i18next middleware the app is using is react-i18next which offers hooks and components that make it easier to integrate i18next into react. The app stores all translations in the resources.json file located in /src/locales/ folder. Read the [Editing Translations](/docs/Translations%20Editor/Editing Translations.md) page to find out how to generate this file.

The app should be configured to display all text in Irish by default. If Irish text does not exist the fallback langugage is English which is the language used to develop the app.

Setting Up the GitHub Workflow​

To enable the "Save to GitHub" functionality for your new project, you'll need to set up the GitHub workflow:

  1. Create a new workflow file in the GitHub repository of your new project:

    • Path: .github/workflows/update-translations.yml
    • Copy the provided workflow file content

  2. Make sure the following parameters within the Translations Editor match your project:

    • Repository name in your TranslationEditorLayout component (repository="new-project")
    • File path parameter in your TranslationEditorLayout (filepath="./src/locales/resources.json")
    • Ensure the GitHub repository exists under the phonlab-tcd organization (as defined in github.js)

  3. Check GitHub repository permissions:

    • The workflow verifies if the user is a collaborator on the repository
    • Make sure your GitHub users have appropriate collaborator access to the repository

  4. No changes are needed to the workflow file itself, but ensure:

    • The master branch is the default branch (the workflow targets this branch)
    • The repository has the necessary GitHub secrets set up (particularly GITHUB_TOKEN)

The workflow is triggered automatically when a user clicks the "Save to GitHub" button in the translation editor interface, which calls the sendGitHubAction function in src/partials/github.js.

Usage in React Components​

react-i18next is imported with the following code.

import { useTranslation } from "react-i18next";

The useTranslation hook is used to retrieve the t function which is used to translate the keys passed to it. In the project all t functions should be renamed to translate during deconstruction. This is to imporve the readability of the code.

EXAMPLE​

const { t: translate } = useTranslation(["translation", "some_namespace"]);

The useTranslation hook takes an optional array of namespaces, which are used to separate the translation keys into different groups. In this case, some_namespace namespace is required. See the Naming Translations page for a description of namespace naming.

The translate function is then used inside of render to return the translated text. This will be Irish by default unless the Irish translation has not been provided by the lab then it will fallback to English.

<MyComponent
  title={translate("some_namespace.some_key")}
  onNext={handleNext}
  onRepeat={handleRepeat}
/>

The library is implemented very similarly in every other component that contains text.