i18n-react

Библиотека i18n-react - это решение для интернационализации (i18n), разработанное для упрощения процесса добавления многоязычной поддержки в приложения React. Разработан на базе i18n-core.

Использование

$3

``bash
npm install @gravity-ui/i18n-react
`

$3

`typescript
import {createIntl} from '@gravity-ui/i18n-react';

const intl = createIntl({
locale: 'en',
allowedLocales: ['ru', 'ru-kz', 'en'],
fallbackLocales: {
'ru-kz': 'ru',
ru: 'en',
},
defaultFallback: 'en',
});
`

$3

Для декларации текстов с учетом особенностей языков и культур мы используем синтаксис ICU MessageFormat.

Библиотека предоставляет два основных способа для отображения переводов:

1. Функция t
Простая функция для получения текстовых переводов. Она игнорирует HTML-теги и возвращает строку в чистом виде.

2. Компонент
Компонент, который поддерживает rich text, позволяя встраивать HTML-теги и другие элементы в переводы.


Примеры использования:

{% list tabs %}

- Обычное сообщение

Декларация:
`typescript
const {t, Message} = intl.createMessages({
text: {
en: 'Text',
},
})
`

t:
`typescript
t('text') // -> Text
`

:
`typescript
// -> Text
`

- Сообщение с аргументом

Декларация:
`typescript
const {t, Message} = intl.createMessages({
activeInstances: {
en: 'Active instances: {count}',
},
})
`

t:
`typescript
t('activeInstances', {count: 1}) // -> Active instances: 1
`

:
`typescript
// -> Active instances: 1
`

- Rich text

⚠️ Важно! Использование возможно только в React через компонент Message.

Декларация:
`typescript
const {Message} = intl.createMessages({
createResourceEmptyText: {
en: 'Вы можете перейти на страницу создания ресурса',
},
})
`

:
`tsx
id="createResourceEmptyText"
values={{
link: chunks => {chunks}
}}
/>
`

- Markdown

⚠️ Важно! Для использования нужно подключить плагин к сборке проекта.

Декларация:
`typescript
const {t, Message} = intl.createMessages({
open: {
ru: 'Больше примеров синтаксиса в документации',
}
})
`

t:
`typescript
t('open') // ->

Больше примеров синтаксиса в документации


`

:

* Необходимо использовать "ignoreTag" для Message компонента

`typescript
// ->

Больше примеров синтаксиса в документации


`

{% endlist %}

$3

Вы можете прочитать большое о фолбеках в i18n-core/fallback-locales.

Конфигурация инстанса интернационализации

- locale - изначальная локаль.
- allowedLocales - локали, используемые в проекте. Каждый перевод будет содержать значение для каждой локали.

Конфигурация фолбеков:
- fallbackLocales, defaultFallback, disableUseLocaleLangAsFallback - вы можете прочитать большое о фолбеках в i18n-core/fallback-locales.

Базовые FormatJS свойства (документация):
- formats, defaultFormats - часть от базовых formats, defaultFormats. Поддерживается только numbers формат.
- defaultRichTextElements
- textComponent
- wrapRichTextChunksInFragment
- onError
- onWarn

Методы инстанса интернационализации

- createMessages - создание переводов, возвращает t функцию и компонент.
- setLocale - изменить текущую локаль.
- getLocale - получить текущую локаль.
- getCurrentFallbackLocales - получить список приоретезированных фолбеков для текущей локали.

Рекомендуемые плагины

$3

Для оптимизации размера поставляемых на клиент ключей нужно использовать плагин:

- i18n-babel-plugin - если вы используете babel

- i18n-optimize-plugin - если вы не используете babel

Плагин выполняет следующие операции с i18n.ts:
- Удаляет meta из сообщений (id, description, etc.)
- Преобразует markdown в html (при meta.markdown === true)
- Применяет типограф к содержимому ключей

$3

Для удобства работы рекомендуется использовать существующие eslint правила из пакета eslint-plugin-i18n:
- auto-generate-translation-message-id - авто-генерация id для создаваемых переводов. Только для проектов, использующих интеграцию с танкером или другим хранилищем переводов.
- restrict-i18n-imports - правило запрещает импорт переводов из i18n.ts` файлов, расположенных на другом уровне вложенности (кроме исключений).Правило позволяет сохранять принятый подход к хранению ключей - рядом с местом использования.