@gravity-ui/i18n-node

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

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

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

i18n-node

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

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

Установка

npm install @gravity-ui/i18n-node

Инициализация инстанса интернационализации

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

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

const instance = intl.getLocaleInstance('en')

Создание и использование переводов

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

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

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

{% list tabs %}

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

    Декларация:

    const {messages} = intl.createMessages({
        text: {
            en: 'Text',
        },
    })
    const {t} = instance.useMessages(messages);
    

    t:

    t('text') // -> Text
    
  • Сообщение с аргументом

    Декларация:

    const {messages} = intl.createMessages({
        activeInstances: {
            en: 'Active instances: {count}',
        },
    })
    const {t} = instance.useMessages(messages);
    

    t:

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

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

    Декларация:

    const {messages} = intl.createMessages({
        open: {
            ru: 'Больше примеров синтаксиса в [документации](https://diplodoc.com/docs/ru/index-yfm)',
        }
    })
    const {t} = instance.useMessages(messages);
    

    t:

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

{% endlist %}

Фолбеки

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

Смена локали

Чтобы изменить локаль используйте метод создалия локального инстанса: intl.getLocaleInstance([locale]).

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

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

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

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

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

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

  • createMessages - создание переводов, возвращает t функцию.
  • getLocaleInstance - создать инстанс intl для переданной локали, для последующего получения переводов. Созданные инстансы кешируются.

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

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-node 共发布 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-node 的常见问题

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

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

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

在项目目录运行 npm install @gravity-ui/i18n-node,或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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