@gravity-ui/i18n-core

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

The i18n-core library is the foundation for internationalization (i18n) libraries. Built on top of @formatjs/intl.

原始使用文档
文档目录4 节
  1. Key Features:
  2. Usage Examples:
  3. Usage
  4. Locale Fallbacks

i18n-core

The i18n-core library is the foundation for internationalization (i18n) libraries. Built on top of @formatjs/intl.

Key Features:

  1. Framework Agnostic: Designed to work with any JavaScript or TypeScript project, React-based or not.

  2. Built on top of @formatjs/intl: Leverages the powerful formatting and customization capabilities of @formatjs/intl, providing industry-standard localization functionality.

  3. Modular and Extensible: The architecture allows for extending or customizing functionality according to your project's requirements.

Usage Examples:

  • React applications: easily integrates with React projects using the i18n-react library.
  • Server-side solutions: easily integrates with server-side solutions using the i18n-node library.

Usage

Locale Fallbacks

Configuration:

  • fallbackLocales - fallbacks for defined locales.
  • defaultFallback - default fallback. It will be used if no higher priority fallback is found. Available options:
    • empty-string - fallback to empty string.
    • key - fallback to translation key.
    • One of the locales used in the project allowedLocales, or their list.
  • For defaultFallback empty-string or key, the same behavior applies when a key is missing from the keyset passed to createMessages (there is no entry for that key at all). If defaultFallback is a locale or a list of locales, a missing key still cannot be resolved and results in a missing-translation error, same as when a key exists but has no string in any fallback locale.
  • disableUseLocaleLangAsFallback - disable using locale language as its fallback. More details can be found in the fallback search section.

Fallbacks for locale='ru-kz':

  1. Use fallbackLocales['ru-kz'], if present
  2. If disableUseLocaleLangAsFallback === false:
    • Detect locale using Intl.Locale. In our case Intl.Locale('ru-kz').language === 'ru'
    • Use allowedLocales[Intl.Locale('ru-kz').language], if present
    • Use fallback for Intl.Locale('ru-kz').language. For search, use this same algorithm from the beginning.
  3. Use defaultFallback

Example:

{% list tabs %}

  • Using fallbackLocales and defaultFallback

    i18n instance config:

    {
       allowedLocales: ['en', 'ru', 'ru-kz'],
       fallbackLocales: {
          'ru-kz': 'ru',
          'ru': 'en'
       },
       defaultFallback: 'empty-string'
    }
    

    Fallbacks by languages:

    • en - empty string
    • ru - en, empty string
    • ru-kz - ru, en, empty string
  • Using locale language as fallback

    Internationalization instance configuration:

    {
       allowedLocales: ['en', 'ru', 'ru-kz'],
       fallbackLocales: {},
       defaultFallback: 'empty-string',
       disableUseLocaleLangAsFallback: false
    }
    

    Fallbacks by languages:

    • en, ru - empty string
    • ru-kz - ru, empty string

{% endlist %}

版本与发布记录

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

版本发布日期距今
1.6.0latest2026/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-core 的常见问题

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

The i18n-core library is the foundation for internationalization (i18n) libraries. Built on top of @formatjs/intl.

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

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

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

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

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

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

@gravity-ui/i18n-core 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >= 18。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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