@gravity-ui/i18n-optimize-plugin

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

Plugin for optimizing translation file delivery. Can be used with webpack, rspack, and vite.

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

@gravity-ui/i18n-optimize-plugin

Plugin for optimizing translation file delivery. Can be used with webpack, rspack, and vite.

Under the hood, uses i18n-babel-plugin.

Transforms i18n.ts files (other names can be configured via filenameMatcher):

  • Removes meta from messages (id, description, etc.)
  • Converts markdown to html (when meta.markdown === true)
  • Applies typograf rules to key content
  • Creates per-locale chunks and optimizes their runtime loading

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-optimize-plugin --save-dev

Connect the plugin to the build. Example if you're using app-builder with 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);
        }
    },
});

Example if you're using app-builder with 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);
        }
    },
});

Settings

config

Project config with the locales the plugin optimizes translations for.

By default i18n.config.ts is searched for from the current working directory up to the repository or workspace root. Pass this option to point the plugin at the config explicitly — either as an object or as a path to the config file:

import i18nConfig from './i18n.config';

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

Passing the config as an object also skips the config lookup entirely.

filenameMatcher

Allows processing translation files with custom names. Mirrors the filenameMatcher option of i18n-babel-plugin.

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.

Default: 'i18n.ts'.

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

Files that match are still skipped if they contain no createMessages or declareMessages call.

typograf

Allows configuring typograf rules.

By default, uses DEFAULT_TYPOGRAF_CONFIG rules.

Example of customizing typograf rules:

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

Example of disabling typograf:

applyI18nOptimizePlugin(webpackConfig, {
    typograf: false,
})

optimizeLocaleChunks

Optimizes chunk loading at runtime: only translations for the current language are loaded to the client.

Works only in production mode for webpack/rspack. Disabled by default (false).

How to enable?

  1. For proper chunk loading, you need to define the runtimeLanguageVariableName variable with the current user language in window.

    For example, if you're using core, you can do this through inlineScripts:

    return res.renderLayout2({
        inlineScripts: [
            `window.I18N_LANG = "${userLanguage}";`,
            'window.YC = window.__DATA__;'
        ],
    })
    
By default, `window.I18N_LANG` is used for `runtimeLanguageVariableName`.
  1. Configure dynamic manifest depending on user language (production only).

    For example, when using core this can be done through middleware:

    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. Enable the optimizeLocaleChunks option in plugin settings.

  3. Add the line .compiled-locales* to .arcignore.

Optimization Strategies

The strategy parameter determines how language chunks are formed:

  • by-module (default) - separate language chunks are created for each i18n.ts module. This allows loading translations only for modules used on the page.

  • all-in-one - creates a common chunk for each language containing all project translations. Suitable for small projects where translation volume is small.

  • custom - custom strategy allowing you to define your own chunk naming logic through the getChunkName function.

Language Variable Configuration

The runtimeLanguageVariableName parameter allows specifying the variable name that stores the current language. By default, window.I18N_LANG is used.

Example of enabling optimization:

// 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 是什么?

Plugin for optimizing translation file delivery. Can be used with webpack, rspack, and vite.

如何安装 @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 和提交记录判断。