@gravity-ui/i18n-cli

中文文档
1.6.0发布于 2026/11/03MITTypeScriptESM + CJS构建来源已验证近 30 天下载 1.8万
  • Provides i18n configuration for the project
原始使用文档
文档目录10 节
  1. Project Setup
  2. Commands
  3. create-keys
  4. find-unused
  5. Configuration options
  6. allowedLocales
  7. fallbackLocales
  8. defaultFallback
  9. clientIntlModule
  10. serverIntlModule

@gravity-ui/i18n-cli

  • Provides i18n configuration for the project

  • Provides the i18n-cli command for managing language files in the project.

Project Setup

  1. Install the package:

    npm i -D @gravity-ui/i18n-cli
    
  2. Createthe config file i18n.config.ts in the project root:

    import {defineConfig} from '@gravity-ui/i18n-cli/config';
    
    export default defineConfig({
        allowedLocales: ['ru', 'en', 'ru-kz', 'en-kz'] as const,
        fallbackLocales: {
            'ru-kz': 'ru',
            'en-kz': 'en',
        },
        defaultFallback: 'en',
        clientIntlModule: {
            path: 'src/shared/i18n/intl.ts',
            alias: '@shared/i18n',
        },
    });
    
  3. Import the config in the i18n library instance (i18n-react and i18n-node)

    import {createIntl} from '@gravity-ui/i18n-react';
    import i18nConfig from '../../../i18n.config';
    
    const {allowedLocales, fallbackLocales, defaultFallback} = i18nConfig;
    
    export const intl = createIntl({
        allowedLocales,
        fallbackLocales,
        defaultFallback,
    });
    

Commands

create-keys

Checks the provided file/directory for calls to missing keys and adds them to the i18n.ts file.

Run for a single file

npx i18n-cli create-keys src/ui/SomeComponent/SomeComponent.tsx

Run for all files in a directory

npx i18n-cli create-keys src/ui/ComponentDirectory

find-unused

Recursively search for unused keys starting from the specified directory.

Report on unused keys

npx i18n-cli find-unused src/ui/SomeComponent

Delete unused keys

npx i18n-cli find-unused -d src/ui/SomeComponent

Configuration options

allowedLocales

Type: string[]

Allowed locales in the project.

{
    allowedLocales: ['ru', 'en'] as const,
}

fallbackLocales

Fallbacks for given locales. More details can be found in i18n-core.

defaultFallback

Default fallback. Used if no higher priority fallback is found. More in i18n-core.

clientIntlModule

Location of the library instance for the client-side i18n-react in the project.

{
    clientIntlModule: {
        // Path to the module with intl library instance
        path: 'src/ui/shared/i18n.ts',

        // TypeScript alias of the module with intl library instance
        alias: '@shared/i18n';
    }
}

serverIntlModule

Server-side library instance location i18n-node in the project.

{
    serverIntlModule: {
        // Path to the module containing the intl library instance
        path: 'src/server/utils/i18n.ts',

        // TypeScript alias of the module containing the intl library instance
        alias: undefined,

        // Regular expressions that determine if a module belongs to the server-side
        pathMatchers: [/src\/server\/.+$/]
    }
}

版本与发布记录

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

版本发布日期距今
1.6.0latest2026/11/0313 天前
1.5.02026/11/0313 天前
1.4.22026/08/192 个月前
1.4.12026/04/047 个月前
1.4.02026/03/168 个月前
1.3.22026/02/139 个月前

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

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

Provides i18n configuration for the project

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

在项目目录运行 npm install @gravity-ui/i18n-cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 i18n-cli,可以用 npx i18n-cli 直接运行。

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

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

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

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

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

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

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

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

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

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

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

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