> For the complete documentation index, see [llms.txt](https://intercode.gitbook.io/intercode-saas-kit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://intercode.gitbook.io/intercode-saas-kit/features/internationalization.md).

# Internationalization

### Install dependencies

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

* **i18next**: The core internationalization library.

  ```bash
  yarn add i18next
  ```
* **react-i18next**: The React bindings for i18next.

  ```bash
  yarn add react-i18next
  ```
* **i18next-browser-languagedetector**: A language detector for the browser.

  ```bash
  yarn add i18next-browser-languagedetector
  ```
* **i18next-http-backend**: A backend for loading translations via HTTP.

  ```bash
  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.

```javascript
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`)

```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`)

```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.

```javascript
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

```javascript
import { useTranslation } from 'react-i18next';
```

2. Initialize translations variable in your component

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

3. Use your translations by providing translation path and name

```javascript
t('placeholders.businesses')
```

{% hint style="info" %}
If you are importing more than one resource, use the following syntax:

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

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

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

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

```javascript
t('general:statuses.active');
```

This format allows for easy access to keys from multiple translation files.
{% endhint %}

### API Usage

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

```json
{
    "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."
    }
}
```

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

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

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

```javascript
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'),
    });
}
```

***

{% embed url="<https://www.i18next.com/>" %}