优化 i18n 打包体积与性能

依赖 JSON 文件的传统 i18n 解决方案中最常见的挑战之一是管理内容体积。如果开发者没有手动将内容拆分到各个命名空间（namespaces），用户通常会为了查看一个页面而下载所有页面、甚至是所有语言的翻译。

例如，一个应用有 10 个页面并被翻译成了 10 种语言，可能导致用户为了这 10 个页面下载所有的内容，尽管他们只想要一个页面的内容（当前语言版本的当前页面）。这不仅会造成带宽浪费，也会导致更慢的加载时间。

Intlayer 通过在构建时（build-time）进行优化来解决这一问题。 它可以分析你的代码以检测每个组件实际使用了哪些字典，并只将必要的内容注入到你的打包结果（bundle）中。

目录

分析你的包大小

分析你的打包结果是找出“臃肿”的 JSON 文件和考虑进行代码分割（code-splitting）的首要步骤。这些工具可以生成你应用程序编译代码的树状可视视图（treemap），让你能够清楚地看到究竟是哪些库占据了最多的空间。

npm install -D rollup-plugin-visualizer

import { defineConfig } from "vite";
import { visualizer } from "rollup-plugin-visualizer";

export default defineConfig({
  plugins: [
    visualizer({
      open: true, // 自动在浏览器中打开报告
      filename: "stats.html",
      gzipSize: true,
      brotliSize: true,
    }),
  ],
});

npx next experimental-analyze

npm install -D @next/bundle-analyzer

const withBundleAnalyzer = require("@next/bundle-analyzer")({
  enabled: process.env.ANALYZE === "true",
});

module.exports = withBundleAnalyzer({
  // 你的 Next.js 配置
});

ANALYZE=true npm run build

npm install -D webpack-bundle-analyzer

import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";

export default {
  plugins: [
    new BundleAnalyzerPlugin({
      analyzerMode: "static",
      reportFilename: "bundle-analyzer.html",
      openAnalyzer: false,
    }),
  ],
};

它是如何运作的

Intlayer 使用一种基于组件的方法（per-component approach）。与全局 JSON 文件不同，你的内容会在组件旁边或是组件内部进行定义。在构建流程中，Intlayer 将会：

1. 分析你的代码以寻找 useIntlayer 的调用。
2. 构建对应的字典内容。
3. 替换 useIntlayer 调用为依据你的配置进行优化后的代码。

这样能够确保：

• 如果一个组件未被导入，它的内容将不会包含在打包产物中（Dead Code Elimination / 死代码消除）。
• 如果一个组件被延迟加载，其内容同样会被延迟加载。

插件参考

Intlayer 的构建优化被划分为若干个职责单一的插件。了解它们各自的用途可以防止在配置它们时产生困惑。

Babel 插件 (@intlayer/babel)

这些被直接运用在基于 Webpack 设置的 babel.config.js 当中（比如使用了 Babel 的 Next.js、CRA，或是自定义的 Webpack 等）。

下表按所需的流水线顺序列出它们（与它们必须在 babel.config.js 中出现的顺序相同）：

插件的执行顺序很重要。 在你的 babel.config.js 里，purge 和 minify 的插件必须放置在 optimize 插件之前。优化步骤（optimize）会把 useIntlayer('key') 替换为模糊的 useDictionary(hash)，此举抹除了能够让 purge 和 minify 识别哪些字段被使用过的字典 key 信息。

每一个 Babel 插件都有对应的选项助手（options helper），该助手会在配置加载时读取一遍 intlayer.config.ts，并返回预解析的值：

Vite 插件 (vite-intlayer)

Vite 用户不需要直接对它们进行配置。当你在 vite.config.ts 里调用 withIntlayer() 时，它们会自动生效。只需要在 intlayer.config.ts 中设定 build.purge 和 build.minify，即可开启相应的功能，且不需要额外的插件注册过程。

SWC 插件（@intlayer/swc）

Next.js 用户同样从不直接配置这些。自 v9.2.1 起，next.config.ts 中的 withIntlayer() 仅凭 build.purge 和 build.minify 两个标志就会运行完整流水线 —— 清除、压缩和导入重写。

工作被分成两部分，因为 SWC Wasm 插件一次只转换一个文件，且无法访问文件系统：

判断哪些字段未被使用以及每个字段获得什么别名，需要跨文件状态和文件 I/O，因此这一半在 Node 中运行；SWC 插件只接收生成的表。

各平台配置指南

npm install -D @intlayer/swc

[dependencies]
intlayer-swc-plugin = "*"

import { withIntlayer } from "next-intlayer/server";
import type { NextConfig } from "next";

const nextConfig: NextConfig = {/* 你的配置 */};

export default withIntlayer(nextConfig);

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  build: {
    purge: true, // 从打包的 JSON 中移除未使用的内容字段
    minify: true, // 将内容字段键重命名为简短别名
  },
};

export default config;

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  build: {
    purge: true, // 将未被使用的字段从打好的 JSON 包中移除
    minify: true, // 将字段名重命名为简短的别名
  },
};

export default config;

npm install -D @intlayer/babel

const {
  intlayerExtractBabelPlugin,
  intlayerPurgeBabelPlugin,
  intlayerMinifyBabelPlugin,
  intlayerOptimizeBabelPlugin,
  getExtractPluginOptions,
  getPurgePluginOptions,
  getMinifyPluginOptions,
  getOptimizePluginOptions,
} = require("@intlayer/babel");

module.exports = {
  plugins: [
    // Extract: 编译 .content.ts 文件 → .intlayer/**/*.json
    [intlayerExtractBabelPlugin, getExtractPluginOptions()],

    // Purge: 从 .intlayer/**/*.json 移除不必要的字段
    //    (读取 intlayer.config.ts 内的 build.purge 配置)
    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],

    // Minify: 压缩并重命名 JSON + 源代码里的字段名
    //    (读取 intlayer.config.ts 内的 build.minify 配置)
    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],

    // Optimize: 重写 useIntlayer('key') → useDictionary(hash)
    //    它必须位于末尾，因为该操作会抹去原本的 dictionary 键名。
    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
  ],
};

配置选项

你可通过在你的 intlayer.config.ts 里的 build 属性来控制 Intlayer 怎样去优化你的代码包。

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.CHINESE],
    defaultLocale: Locales.ENGLISH,
  },
  dictionary: {
    importMode: "dynamic",
  },
  build: {
    // 决定在构建时是否直接用直引字典覆盖 useIntlayer() 的调用。
    // undefined = 自动（在生产环境中开启），true = 始终开启，false = 始终关闭。
    optimize: undefined,

    // 将已编译字典里的字段键名改写为简短的字母名称（例如：title → a）。
    // 这将缩小 JSON 的体积；前提条件是启用了 optimize。
    minify: true,

    // 将未曾在代码里真正访问过的内容字段移除。
    // 前提条件是启用了 optimize。
    purge: true,
  },
};

export default config;

在大多数情况之下，推荐为 optimize 保留它的默认值（undefined）。

请参阅配置参考资料以了解所有的选项：配置说明

构建选项

压缩 / Minification (重命名字段键值)

build.minify 并非压缩你的 JavaScript —— 那是你的打包器应该处理的工作。它的工作，是把编译后的字典对应的 JSON 文件的每一个自定义内容的字段，全用短位的字母标识来替代，借此将其体积进行压缩：

// Minify 之前
{ "title": "Hello", "subtitle": "World" }

// Minify 之后
{ "a": "Hello", "b": "World" }

该重新命名的方法同样也会应用到那些处于代码里的属性名访问阶段，所以在最终编译好的结果里，content.title 便会演变为 content.a。它们在运行时的实际表现完全一致。

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  build: {
    minify: true,
  },
};

export default config;

当 optimize 为 false 时，压缩会被跳过。当 editor.enabled 为 true 时，压缩仍会运行，但不执行字段重命名步骤——可视化编辑器通过 keyPath 解析编辑内容，因此原始字段名称必须保留。

在 Next.js 上，当 @intlayer/swc 未安装或无法加载时（Next.js 低于 16.1.0），压缩同样会被跳过。重写源码访问的正是这个插件，因此在没有它的情况下重命名字典，会让你的代码读取已不存在的字段名。

同理，如果是利用了 importMode: 'fetch' 来载入字段时此过程同样不适用。因为它们的内容会以原始命名由后端 API 所提供，对客户端内容随意重命名会破坏客户端与服务端的匹配契约。

字段清除 / Purging (去掉未被引用的字段内容)

build.purge 能自动分析究竟哪些字段真真切切地被你的源代码所引用，进而只把实际引用过的数据予以保留，把其他的垃圾数据从编译生成的 JSON 里排除掉。

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  build: {
    purge: true,
  },
};

export default config;

示例说明: 我们有一个包含五个不同字段数据的字典，但是代码实际就用到了里边的俩：

// Purge 执行前
{ "title": "…", "subtitle": "…", "cta": "…", "footer": "…", "badge": "…" }

// Purge 之后（这里仅仅只用到了 title 与 subtitle）
{ "title": "…", "subtitle": "…" }

当 optimize 为 false 时，清除（Purge）会被跳过。当 editor.enabled 为 true 时，它仍保持启用——被清除的字段不会被任何组件读取，因此编辑器永远不会渲染它。在 Next.js 上，当 @intlayer/swc 不可用以及配置了兼容适配器调用方时，还会被额外跳过。

当检测到某份代码因为异常无法顺利解析、又或者当把由 useIntlayer 输出的值以静态解析器难以预测分析的模式在不同组件中来回丢（比如被打包成对象传入等而未被进行解构）的时候，它同样会跳过，以此保守地保留整部字典的全部信息，避免意外发生。

导入模式（Import Mode）

对于包含多个页面和地区规模比较大的应用程序来说，你的 JSON 可能会占去绝大一部分包（Bundle）的内容。所以，你可以凭借着 importMode 这个参数让 Intlayer 来调整对字典内容本身的实际拉取行为。

全局定义

该参数可以经由你本身的 intlayer.config.ts 这个文件在全局进行指定。

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  dictionary: {
    importMode: "dynamic", // 默认为 'static'
  },
};

export default config;

为字典独立配置

我们也可以在这其中部分独立词典原本配置内的 .content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5|md|mdx|yaml|yml}} 把该参数改写成另外想要的规则。

import { type Dictionary, t } from "intlayer";

const appContent: Dictionary = {
  key: "app",
  importMode: "dynamic", // 将原本的模式改写
  content: {
    // ...
  },
};

export default appContent;

这处 importMode 设置用于指挥组件拉取各项内容的真实手段。要么被指定在了全局 intlayer.config.ts 中的 dictionary 里，要不便以 content.ts 形式来分别定制。

1. 静态模式（Static Mode - default）

在这个默认设定下，Intlayer 自动把全部 useIntlayer 变成了 useDictionary 以做到将所需的翻译数据无缝拼接入 JavaScript 包内。

• 优势（Pros）: 即时就能被加载（属于同步型），由于没有水合（hydration）从而意味着额外的零请求。
• 缺点（Cons）: 但这个包同样也就塞满了给该组件用的各种不同可用语言的对应版本，这非常占空间。
• 最佳应用场合: 单页应用（SPA）。

代码在转换之后的图示（举例）:

// 这是你的原本代码
const content = useIntlayer("my-key");

// (静态) 优化图解。
// 仅为了解释说明而列，出于优化实际上的最终输出略有差别
const content = useDictionary({
  key: "my-key",
  content: {
    nodeType: "translation",
    translation: {
      en: "My title",
      zh: "我的标题",
    },
  },
});

2. 动态模式（Dynamic Mode）

在这一设定之下，Intlayer 自动把全部 useIntlayer 全给变成了 useDictionaryAsync。这个操作能将拉取行文变成动态 import()（这和 Suspense 的表现接近），并有针对性地对当地所在的特殊语言去单独异步请求其实际数据。

• 优势（Pros）: 支持基于地区语言所实施的代码树抖动分离（Tree shaking）。 说白了就是，正在浏览英语界面的使用者仅仅会只被发送那部分英文对应的词典内容，法文或是其他国家的数据都不会加载。
• 缺点（Cons）: 这个阶段下，将会让组件因数据要求而针对各项水合需求（hydration）各自产生不同种的调用申请（拉取各部件内容）。
• 最佳应用场合: 内容巨大且充斥了长文博客的复杂平台、亦或是本身涵盖了大量的翻译种类因而在包（bundle）体积极为严格的情况下使用。

代码在转换之后的图示（举例）:

// 这是你的原本代码
const content = useIntlayer("my-key");

// (动态) 优化图解。
// 仅为了解释说明而列，出于优化实际上的最终输出略有差别
const content = useDictionaryAsync({
  en: () =>
    import(".intlayer/dynamic_dictionary/my-key/en.json").then(
      (mod) => mod.default
    ),
  zh: () =>
    import(".intlayer/dynamic_dictionary/my-key/zh.json").then(
      (mod) => mod.default
    ),
});

使用了 importMode: 'dynamic' 这个方案之时，如果某一页刚好凑齐了 100 个包含了 useIntlayer 内容的部件时，浏览器就有极大的概率朝着服务器丢过去多达 100 种不重样的 fetch 请求。如果意在免于这样的连环「瀑布效应」，尝试尽可能去少写单个的独立 .content （尝试着每几块凑一起合并起来比如每一个大的分块区共享其内容字典，而非是切得那么碎，比如连每一个单小按钮都设单独请求。）如果把多个带有单独名字 .content 内容给附加上相同的 Key 名称，程序依然能够很轻易将这些零散碎落的数据融合成单独庞大且统一的一本完整的字典对象里去。

3. Fetch 模式（Fetch Mode）

行为跟 Dynamic 有所重叠，不过最优先则是朝 Intlayer Live Sync API 请求其词典内容。假如获取数据时遭到拦截或者内容不属于实时的数据内容体系的话，接下来便将其作为兜底顺延递回之前的动切请求。

代码在转换之后的图示（举例）:

// 这是你的原本代码
const content = useIntlayer("my-key");

// 能够将它（Fetch）看成这类实现
const content = useDictionaryAsync({
  en: () =>
    fetch("https://intlayer.my-domain.com/dictionary/my-key/en").then((res) =>
      res.json()
    ),
  zh: () =>
    fetch("https://intlayer.my-domain.com/dictionary/my-key/zh").then((res) =>
      res.json()
    ),
});

如果还需要获得对于 CMS 获取方面的认知的话：可以去查看 CMS 说明

此模式同样会一如既往地因为 JSON 内容会直接借由后端直接输送而不遭受 purge 跟 minify 等等这几类数据剔除方案的干扰。

概要: 静态 和 动态