@gravity-ui/i18n-react

中文文档
1.5.1发布于 2026/04/14MITTypeScriptESM + CJS构建来源已验证近 30 天下载 1.7万

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

原始使用文档
文档目录10 节
  1. Использование
  2. Установка
  3. Создание инстанса интернационализации
  4. Создание и использование переводов
  5. Фолбеки
  6. Конфигурация инстанса интернационализации
  7. Методы инстанса интернационализации
  8. Рекомендуемые плагины
  9. i18n-babel-plugin / i18n-optimize-plugin
  10. eslint-plugin-i18n

i18n-react

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

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

Установка

npm install @gravity-ui/i18n-react

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

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. Компонент <Message />
    Компонент, который поддерживает rich text, позволяя встраивать HTML-теги и другие элементы в переводы.

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

{% list tabs %}

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

    Декларация:

    const {t, Message} = intl.createMessages({
        text: {
            en: 'Text',
        },
    })
    
**`t`:**
```typescript
t('text') // -> Text
```

**`<Message />`:**
```typescript
<Message id="text" /> // -> Text
```
  • Сообщение с аргументом

    Декларация:

    const {t, Message} = intl.createMessages({
        activeInstances: {
            en: 'Active instances: {count}',
        },
    })
    
**`t`:**
```typescript
t('activeInstances', {count: 1}) // -> Active instances: 1
```

**`<Message />`:**
```typescript
<Message id="activeInstances" values={{count: 1}} /> // -> Active instances: 1
```
  • Rich text

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

    Декларация:

    const {Message} = intl.createMessages({
        createResourceEmptyText: {
            en: 'Вы можете перейти на страницу <link>создания ресурса</link>',
        },
    })
    
**`<Message />`:**
```tsx
<Message 
    id="createResourceEmptyText" 
    values={{
        link: chunks => <RouterLink to="/create">{chunks}</RouterLink>
    }}
/>
```
  • Markdown

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

    Декларация:

    const {t, Message} = intl.createMessages({
        open: {
            ru: 'Больше примеров синтаксиса в [документации](https://diplodoc.com/docs/ru/index-yfm)',
        }
    })
    
**`t`:**
```typescript
t('open') // -> <p>Больше примеров синтаксиса в <a href="https://diplodoc.com/docs/ru/index-yfm">документации</a></p>
```

**`<Message />`:**

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

```typescript
<Message id='open' ignoreTag > // -> <p>Больше примеров синтаксиса в <a href="https://diplodoc.com/docs/ru/index-yfm">документации</a></p>
```

{% endlist %}

Фолбеки

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

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

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

Конфигурация фолбеков:

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

Базовые FormatJS свойства (документация):

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

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

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

i18n-babel-plugin / i18n-optimize-plugin

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

Плагин выполняет следующие операции с i18n.ts:

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

eslint-plugin-i18n

Для удобства работы рекомендуется использовать существующие eslint правила из пакета eslint-plugin-i18n:

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

版本与发布记录

@gravity-ui/i18n-react 共发布 11 个版本,首次发布于 2025/10/16;过去 12 个月发布了 9 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.5.1latest2026/04/147 个月前
1.5.02026/03/168 个月前
1.4.22026/02/139 个月前
1.4.12026/02/139 个月前
1.4.02026/02/039 个月前
1.3.22025/12/1311 个月前

关于 @gravity-ui/i18n-react 的常见问题

@gravity-ui/i18n-react 是什么?

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

如何安装 @gravity-ui/i18n-react?

在项目目录运行 npm install @gravity-ui/i18n-react,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^17.0.0 || ^18.0.0 || ^19.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gravity-ui/i18n-react 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gravity-ui/i18n-react 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gravity-ui/i18n-react 可以商用吗?

@gravity-ui/i18n-react 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gravity-ui/i18n-react 的下载量有多少?

根据 npm 官方下载统计,@gravity-ui/i18n-react 在 2026/10/17 – 2026/11/15 这 30 天内被下载 16,684 次,日均约 556 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gravity-ui/i18n-react 还在维护吗?

最新版本 1.5.1 发布于 2026/04/14(7 个月前);至今共发布 11 个版本,其中过去 12 个月发布了 9 个;首次发布于 2025/10/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。