@gravity-ui/i18n-babel-plugin

中文文档
1.5.0发布于 2026/08/12MITTypeScriptCommonJS构建来源已验证近 30 天下载 1.2万

Babel plugin for optimizing translation file delivery.

原始使用文档
文档目录5 节
  1. Usage
  2. Settings
  3. typograf
  4. root
  5. filenameMatcher

@gravity-ui/i18n-babel-plugin

Babel plugin for optimizing translation file delivery.

If you're not using babel, then i18n-optimize-plugin would be suitable for you.

Transforms i18n.ts files:

  • Removes meta from messages (id, description, etc.)
  • Converts markdown to html (when meta.markdown === true)
  • Applies typograf rules to key content

TODO:

  • Validates syntax according to ICU MessageFormat
  • Compiles ICU MessageFormat to AST
  • Replaces original keys with hashes (allows reducing key length)

Usage

Install the plugin:

npm install @gravity-ui/i18n-babel-plugin --save-dev

Connect the plugin to the build. Example if you're using app-builder:

import {defineConfig} from '@gravity-ui/app-builder';

export default defineConfig({
    client: {
        babel: (config) => {
            const plugins = config.plugins ? [...config.plugins] : [];

            return {
                ...config,
                plugins: [
                    ...plugins,
                    require.resolve('@gravity-ui/i18n-babel-plugin')
                ],
            };
        }
    }
});

Settings

typograf

Allows configuring typograf rules.

By default, uses DEFAULT_TYPOGRAF_CONFIG rules.

Example of customizing typograph rules:

plugins: [
    require.resolve('@gravity-ui/i18n-babel-plugin', {
        typograf: {
            enabled: ['common/nbsp/afterNumber', 'common/nbsp/afterParagraphMark'],
            disabled: ['common/symbols/cf', 'common/space/trimRight', 'common/space/trimLeft'],
        }
    })
],

Example of disabling typograph:

plugins: [
    require.resolve('@gravity-ui/i18n-babel-plugin', {
        typograf: false,
    })
],

root

Allows limiting the plugin's scope. The plugin will not process files outside the specified scope.

Type: string.

Default: src.

filenameMatcher

Allows processing translation files with custom names.

Type: FilenameMatcher | FilenameMatcher[], where FilenameMatcher is:

  • string — compared with the end of the file path, so i18n.ts matches both Component/i18n.ts and Component/component.i18n.ts;
  • RegExp — tested against the normalized path (\ → /);
  • {type: 'regexp', pattern: string, flags?: string} — the same regexp in a serializable form (for .babelrc / JSON configs).

Default: 'i18n.ts'.

Example with custom file names:

plugins: [
    require.resolve('@gravity-ui/i18n-babel-plugin', {
        filenameMatcher: ['i18n.ts', 'keysets.ts'],
    })
],

Example with a regexp (matches Component/component.translations.ts and Component/component.translations.tsx):

plugins: [
    require.resolve('@gravity-ui/i18n-babel-plugin', {
        filenameMatcher: /\.translations\.tsx?$/,
    })
],

The same regexp in .babelrc:

{
  "plugins": [
    ["@gravity-ui/i18n-babel-plugin", {
      "filenameMatcher": {"type": "regexp", "pattern": "\\.translations\\.tsx?$"}
    }]
  ]
}

Note that the root restriction still applies: files outside root are not processed even if they match filenameMatcher.

版本与发布记录

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

版本发布日期距今
1.5.0latest2026/08/123 个月前
1.4.02026/03/168 个月前
1.3.22026/02/139 个月前
1.3.12026/02/139 个月前
1.3.02026/02/039 个月前
1.2.22025/12/1311 个月前

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

@gravity-ui/i18n-babel-plugin 是什么?

Babel plugin for optimizing translation file delivery.

如何安装 @gravity-ui/i18n-babel-plugin?

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

@gravity-ui/i18n-babel-plugin 支持 TypeScript 吗?

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

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

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

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

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

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

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

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

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

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

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