Библиотека **i18n-react** - это решение для интернационализации (i18n), разработанное для упрощения процесса добавления многоязычной поддержки в приложения React. Разработан на базе **[i18n-core](../i18n-core/)**.
npm install @gravity-ui/i18n-reactБиблиотека i18n-react - это решение для интернационализации (i18n), разработанное для упрощения процесса добавления многоязычной поддержки в приложения React. Разработан на базе i18n-core.
``bash`
npm install @gravity-ui/i18n-react
`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',
});
`
Для декларации текстов с учетом особенностей языков и культур мы используем синтаксис 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`
- Сообщение с аргументом
Декларация:
`typescript`
const {t, Message} = intl.createMessages({
activeInstances: {
en: 'Active instances: {count}',
},
})
t:
`typescript`
t('activeInstances', {count: 1}) // -> Active instances: 1
:
`typescript`
- Rich text
⚠️ Важно! Использование возможно только в React через компонент Message.
Декларация:
`typescript`
const {Message} = intl.createMessages({
createResourceEmptyText: {
en: 'Вы можете перейти на страницу создания ресурса',
},
})
:
`tsx`
values={{
link: chunks =>
}}
/>
- Markdown
⚠️ Важно! Для использования нужно подключить плагин к сборке проекта.
Декларация: Больше примеров синтаксиса в документации
`typescript`
const {t, Message} = intl.createMessages({
open: {
ru: 'Больше примеров синтаксиса в документации',
}
})
t
:`
typescript`
t('open') // ->
:
* Необходимо использовать "ignoreTag" для Message компонента
` Больше примеров синтаксиса в документацииtypescript`
{% endlist %}
Вы можете прочитать большое о фолбеках в 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
- - получить список приоретезированных фолбеков для текущей локали.
Для оптимизации размера поставляемых на клиент ключей нужно использовать плагин:
- i18n-babel-plugin - если вы используете babel
- i18n-optimize-plugin - если вы не используете babel
Плагин выполняет следующие операции с i18n.ts:meta.markdown === true
- Удаляет meta из сообщений (id, description, etc.)
- Преобразует markdown в html (при )
- Применяет типограф к содержимому ключей
Для удобства работы рекомендуется использовать существующие eslint правила из пакета eslint-plugin-i18n:
- auto-generate-translation-message-id - авто-генерация id для создаваемых переводов. Только для проектов, использующих интеграцию с танкером или другим хранилищем переводов.i18n.ts` файлов, расположенных на другом уровне вложенности (кроме исключений).Правило позволяет сохранять принятый подход к хранению ключей - рядом с местом использования.
- restrict-i18n-imports - правило запрещает импорт переводов из