Internationalization

Here you can learn how to setup internationalization via i18next

Install dependencies

To use i18next with React and the specified plugins, you need to install the following dependencies:

• i18next: The core internationalization library.

  yarn add i18next

• react-i18next: The React bindings for i18next.

  yarn add react-i18next

• i18next-browser-languagedetector: A language detector for the browser.

  yarn add i18next-browser-languagedetector

• i18next-http-backend: A backend for loading translations via HTTP.

  yarn add i18next-http-backend

Initialize i18next

This code initializes i18next, setting up internationalization with several configurations:

• .use(initReactI18next): Initializes i18next for React, providing React-specific features.

• .use(I18nextBrowserLanguageDetector): Adds automatic browser-based language detection, which selects the user's language based on their browser settings.

• .use(I18NextHttpBackend): Configures the backend to load translation files from an HTTP endpoint, specified in the loadPath of the main init configuration.

---

• fallbackLng: 'en': English is the default language if no preference is detected.

• load: 'languageOnly': Only the base language (e.g., en) is loaded, without region variants.

• supportedLngs: ['en', 'uk']: Supports English and Ukrainian.

• backend.loadPath: Specifies the path to translation JSON files for language and namespace.

• defaultNS: 'common': Sets the default namespace.

• useSuspense: false: Disables suspense in React for smoother integration without loading delays.

import i18next from 'i18next';
import { initReactI18next } from 'react-i18next';
import I18nextBrowserLanguageDetector from 'i18next-browser-languagedetector';
import I18NextHttpBackend from 'i18next-http-backend';

i18next
    .use(initReactI18next)
    .use(I18nextBrowserLanguageDetector)
    .use(I18NextHttpBackend)
    .init({
        fallbackLng: 'en',
        load: 'languageOnly',
        supportedLngs: ['en', 'uk'],
        interpolation: {
            escapeValue: false,
        },
        backend: {
            loadPath: '/locales/{{lng}}/{{ns}}.json',
        },
        react: {
            useSuspense: false,
        },
        defaultNS: 'common',
    });

Directory Structure ( Resource setup )

1. Create locales Directory Inside the public folder of your UI, create a directory named locales.

2. Language Directories Within the locales directory, create separate directories for each language you will support, using abbreviations such as:

   • uk for Ukrainian

   • en for English

3. Resource Files Inside each language directory, create a JSON file with resource name like general.json. Populate these files with structured translations.

English (en/general.json)

{
    "home": "Home",
    "dashboard": "Dashboard",
    "settings": "Settings",
    "search": "Search",
    "language": "Language",
    "error": "Error",
    "success": "Success",
    "none": "None",
    "or": "Or",
    "field": "field"
}

Ukrainian (uk/general.json)

{
    "home": "Головна",
    "dashboard": "Панель управління",
    "settings": "Налаштування",
    "search": "Пошук",
    "language": "Мова",
    "error": "Помилка",
    "success": "Операція успішна",
    "none": "Немає",
    "or": "Або",
    "field": "поле"
}

Notifications configuration

The requestNotification method is designed to trigger notifications with dynamic content based on a set of parameters:

• Parameters: It takes an object with keys type (notification type), resource (subject), action (performed action), and plural (boolean for noun plurality).

• Message Structure: Based on plural, it selects either the singular or plural form of the resource (resourceI18n).

• API Call: The notification API is called with a title and a description, both localized with i18next. The description includes resource, noun, and action, where the action is continuous and lowercase.

This setup ensures adaptable, internationalized notifications for various actions and resources.

const requestNotification = ({ type, resource, action, plural }) => {
    const nounType = plural ? 'plural' : 'singular';

    const resourceI18n = t(`notifications:resources.${resource}.${nounType}`);

    api[type]({
        message: t(`general:${type}`),
        description: t(`notifications:${type}`, {
            resource: resourceI18n,
            noun: t(`notifications:noun.${nounType}`),
            action: t(`general:actions.continuous.${action}`).toLowerCase(),
        }),
        placement: 'top',
    });
};

UI Usage

1. Import useTranslation hook for react-i18next library

import { useTranslation } from 'react-i18next';

1. Initialize translations variable in your component

const { t } = useTranslation(['dashboard']);

1. Use your translations by providing translation path and name

t('placeholders.businesses')

If you are importing more than one resource, use the following syntax:

useTranslation(['users', 'general', 'confirmModal', 'apiResponses']);

The first resource will be selected automatically with every usage. For example:

t('placeholders.businesses'); // This will resolve to users:placeholder.businesses

To use a different resource, provide the resource name followed by a colon (:):

t('general:statuses.active');

This format allows for easy access to keys from multiple translation files.

API Usage

1. Create the apiResponses translations file with the following content:

{
    "EMAIL_NOT_FOUND": {
        "message": "To proceed, please sign up",
        "description": "You don't have any accounts yet."
    },
    "INCORRECT_CREDENTIALS": {
        "message": "Incorrect email or password",
        "description": "The email or password you entered is incorrect. Please try again or contact support if you are unable to access your account."
    },
    "EMAIL_EXISTS": {
        "message": "Error",
        "description": "A user with this email is already registered."
    }
}

1. When throwing exceptions, set the error code as follows:

throw new HttpException(
    {
        message: 'Error',
        description: 'A user with this email is already registered.',
        code: 'EMAIL_EXISTS'
    },
    400
);

1. To manage API responses using the openNotification configuration, implement error handling as follows:

catch (error) {
    const { code } = error.response.data;

    openNotification({
        type: notificationType.ERROR,
        message: code ? t(`apiResponses:${code}.message`) : t('notification.error.message'),
        description: code ? t(`apiResponses:${code}.description`) : t('notification.error.description'),
    });
}

---

Introductioni18next documentation