# @gravity-ui/i18n-optimize-plugin 中文文档

规范地址：https://npmcn.com/package/%40gravity-ui/i18n-optimize-plugin/

版本：1\.5\.3
npm 元数据更新时间：2026-11-03T15:24:26.927Z
中文译文更新时间：2026-11-17T01:03:44.746Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gravity-ui/i18n-optimize-plugin
原文对照：https://npmcn.com/package/%40gravity-ui/i18n-optimize-plugin/?lang=original
项目主页：https://github.com/gravity-ui/i18n#readme
源码仓库：https://github.com/gravity-ui/i18n

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：62.9 kB，36 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>= 18
- 运行依赖：9 个
- 首次发布：2025-10-16T14:34:41.611Z
- 最新版本发布：2026-11-03T15:24:26.487Z
- 近 30 天下载量：12406（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 14 个）

## 中文简介

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

## 安装

```sh
npm install @gravity-ui/i18n-optimize-plugin
```

也可以使用：`pnpm add @gravity-ui/i18n-optimize-plugin`、`yarn add @gravity-ui/i18n-optimize-plugin`、`bun add @gravity-ui/i18n-optimize-plugin`

## README

# @gravity-ui/i18n-优化-plugin

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

盖下,用 [`i18n-babel-plugin`](https://npmcn.com/package/%40gravity-ui/i18n-babel-plugin/README.md)。 。 。 .

_变换 `i18n.ts` 文件(其他名称可通过 [`filenameMatcher`](https://npmcn.com/package/%40gravity-ui/i18n-optimize-plugin/#readme-filenamematcher):_

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

_东都:_

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

## 使用量

安装插件 :

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

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

```ts
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`数字 :

```ts
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` 从当前工作目录搜索到仓库 或工作空间根。 通过此选项可以将插件明确指向配置 对象或配置文件的路径 :

```ts
import i18nConfig from './i18n.config';

applyI18nOptimizePlugin(webpackConfig, {
    config: i18nConfig,
})
```

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

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

### 文件名Matcher

允许使用自定义名称处理翻译文件 。 镜像 [`filenameMatcher` 选项 `i18n-babel-plugin`](https://npmcn.com/package/%40gravity-ui/i18n-babel-plugin/README.md#filenamematcher)。 。 。 .

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

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

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

```ts
applyI18nOptimizePlugin(webpackConfig, {
    filenameMatcher: ['i18n.ts', 'keysets.ts'],
})
```

```ts
applyI18nOptimizePlugin(webpackConfig, {
    filenameMatcher: /\.translations\.tsx?$/,
})
```

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

### 错误

允许配置 [类型规则](https://github.com/typograf/typograf/blob/dev/docs/RULES.ru.md)。 。 。 .

默认使用 [`DEFAULT_TYPOGRAF_CONFIG`](https://npmcn.com/package/%40gravity-ui/i18n-optimize-plugin/src/typograf.ts) 规则.

定制打字规则的例子:

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

无效打字的例子:

```ts
applyI18nOptimizePlugin(webpackConfig, {
    typograf: false,
})
```

### 优化本地商家

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

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

#### 如何启动?

1.  对于适当的块装入,需要定义 `runtimeLanguageVariableName` 变量,在窗口中使用当前用户语言.
    
    例如,如果你在使用 `core`你可以做到这一点通过 `inlineScripts`数字 :
    
    ```ts
    return res.renderLayout2({
        inlineScripts: [
            `window.I18N_LANG = "${userLanguage}";`,
            'window.YC = window.__DATA__;'
        ],
    })
    ```
    

```
By default, `window.I18N_LANG` is used for `runtimeLanguageVariableName`.
```

1.  根据用户语言配置动态表(仅生产).
    
    例如,当使用时 `core` 这可以通过中间软件实现 :
    
    ```ts
    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` 已使用.

实现优化的实例:

```ts
// 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 是什么？

用于优化翻译文件交付的插件 。 可用于网络包装,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 和提交记录判断。

