@gravity-ui/i18n-optimize-plugin

中文文档
1.5.3发布于 2026/11/03MITTypeScriptES Module构建来源已验证近 30 天下载 1.2万

用于优化翻译文件交付的插件 。 可用于网络包装,rspack,和活地.

中文使用文档
文档目录6 节
  1. 使用量
  2. 设置
  3. 配置
  4. 文件名Matcher
  5. 错误
  6. 优化本地商家

@gravity-ui/i18n-优化-plugin

用于优化翻译文件交付的插件 。 可用于网络包装,rspack,和活地.

盖下,用 i18n-babel-plugin。 。 。 .

变换 i18n.ts 文件(其他名称可通过 filenameMatcher:

  • 从信件中删除元( id, 描述等)
  • 将下标记转换为 html( 当 meta.markdown === true(中文(简体) )
  • 对关键内容应用打字规则
  • 每个本地块创建并优化其运行时间加载

东都:

  • 根据 ICU 信件格式验证语法
  • 编译 ICU 信件格式到 AST
  • 将原始密钥替换为散列( 允许缩短密钥长度)

使用量

安装插件 :

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

连接插件到构建中 。 实例,如果你在使用 app-builder 与 rspack数字 :

import {defineConfig} from '@gravity-ui/app-builder';
import applyI18nOptimizePlugin from '@gravity-ui/i18n-optimize-plugin/rspack';

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

            return applyI18nOptimizePlugin(config);
        }
    },
});

实例,如果你在使用 app-builder 与 webpack数字 :

import {defineConfig} from '@gravity-ui/app-builder';
import applyI18nOptimizePlugin from '@gravity-ui/i18n-optimize-plugin/webpack';

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

            return applyI18nOptimizePlugin(config);
        }
    },
});

设置

配置

工程配置本地端, 插件可以优化翻译 .

默认 i18n.config.ts 从当前工作目录搜索到仓库 或工作空间根。 通过此选项可以将插件明确指向配置 对象或配置文件的路径 :

import i18nConfig from './i18n.config';

applyI18nOptimizePlugin(webpackConfig, {
    config: i18nConfig,
})
applyI18nOptimizePlugin(webpackConfig, {
    config: require.resolve('./i18n.config.ts'),
})

通过配置作为对象也会完全跳过配置的取景.

文件名Matcher

允许使用自定义名称处理翻译文件 。 镜像 filenameMatcher 选项 i18n-babel-plugin。 。 。 .

类型 : FilenameMatcher | FilenameMatcher[]时 FilenameMatcher 为:

  • string —— 与文件路径的结尾相比, 所以 i18n.ts 匹配两者 Component/i18n.ts 财务报告和审定财务报表 Component/component.i18n.ts· ;
  • RegExp ——按常态化路径进行考核(\ → /(三);
  • {type: 'regexp', pattern: string, flags?: string} ——以可序列形式出现的同一种正则说明.

默认 : 'i18n.ts'。 。 。 .

applyI18nOptimizePlugin(webpackConfig, {
    filenameMatcher: ['i18n.ts', 'keysets.ts'],
})
applyI18nOptimizePlugin(webpackConfig, {
    filenameMatcher: /\.translations\.tsx?$/,
})

匹配的文件如果包含无则仍然被跳过 createMessages 或者说 declareMessages 电话.

错误

允许配置 类型规则。 。 。 .

默认使用 DEFAULT_TYPOGRAF_CONFIG 规则.

定制打字规则的例子:

applyI18nOptimizePlugin(webpackConfig, {
    typograf: {
        enabled: ['common/nbsp/afterNumber', 'common/nbsp/afterParagraphMark'],
        disabled: ['common/symbols/cf', 'common/space/trimRight', 'common/space/trimLeft'],
    }
})

无效打字的例子:

applyI18nOptimizePlugin(webpackConfig, {
    typograf: false,
})

优化本地商家

在运行时优化块加载:只有当前语言的翻译才加载到客户端.

只在网络包装/软件包装的生产模式中工作。 默认禁用( 假) .

如何启动?

  1. 对于适当的块装入,需要定义 runtimeLanguageVariableName 变量,在窗口中使用当前用户语言.

    例如,如果你在使用 core你可以做到这一点通过 inlineScripts数字 :

    return res.renderLayout2({
        inlineScripts: [
            `window.I18N_LANG = "${userLanguage}";`,
            'window.YC = window.__DATA__;'
        ],
    })
    
By default, `window.I18N_LANG` is used for `runtimeLanguageVariableName`.
  1. 根据用户语言配置动态表(仅生产).

    例如,当使用时 core 这可以通过中间软件实现 :

    import {createMiddleware, getDefaultManifestPath} from '@gravity-ui/ui-core-layout';
    
    export const layoutMiddleware = createMiddleware(({lang}) => {
        let manifestName = 'assets-manifest.json';
    
        if (process.env.NODE_ENV === 'production' && lang) {
            manifestName = `assets-manifest.${lang}.json`;
        }
    
        return getDefaultManifestPath(manifestName);
    });
    
  2. 启用 optimizeLocaleChunks 选项.

  3. 添加行号 .compiled-locales* 改为 .arcignore。 。 。 .

优化战略

这个 strategy 参数决定语言块的形成方式 :

  • by-module (默认) - 为每个创建单独的语言块 i18n.ts 模块。 这只允许为页面中使用的模块加载翻译.

  • all-in-one - 为每种语言建立一个包含所有项目翻译的共同块。 适用于翻译量小的小项目.

  • custom - 自定义策略,允许您通过 getChunkName 函数.

语言可变配置

这个 runtimeLanguageVariableName 参数允许指定存储当前语言的变量名称。 默认, window.I18N_LANG 已使用.

实现优化的实例:

// Default by-module strategy
applyI18nOptimizePlugin(webpackConfig, {
    optimizeLocaleChunks: true,
})

// all-in-one strategy
applyI18nOptimizePlugin(webpackConfig, {
    optimizeLocaleChunks: {
        strategy: 'all-in-one',
    },
})

// Changing runtime variable that stores user language
applyI18nOptimizePlugin(webpackConfig, {
    optimizeLocaleChunks: {
        strategy: 'by-module',
        runtimeLanguageVariableName: 'window.USER_LANG',
    },
})

版本与发布记录

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

版本发布日期距今
1.5.3latest2026/11/0313 天前
1.5.22026/11/0313 天前
1.5.12026/08/192 个月前
1.5.02026/08/123 个月前
1.4.12026/04/047 个月前
1.4.02026/03/168 个月前

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

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

用于优化翻译文件交付的插件 。 可用于网络包装,rspack,和活地.

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

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

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

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

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

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

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

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

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

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

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

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

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

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