Lingui 动态加载消息目录:用 i18n.load 按需加载,砍掉首屏多余的语言包
Lingui 动态加载消息目录:用 i18n.load 按需加载,砍掉首屏多余的语言包
在现代应用中,把"默认 locale"以外的语言消息一次性打进初始 bundle 是一种常见却浪费的做法。本文基于 Lingui 官方指南 动态加载消息目录,完整讲解如何用 i18n.load + 动态 import() 实现"只加载当前语言所需目录"的运行时加载方案,并结合 I18n 核心实现、I18nProvider 源码 以及仓库中的 Next.js 示例,说明这套方案为什么能工作、首屏请求实际发生什么变化,最后介绍配套的 Dependency Tree Extractor(实验特性),从"提取"到"加载"两端协同,进一步压缩每个入口的目录体积。
为什么需要动态加载目录
默认情况下,Lingui 让"加载单一活动 locale 的全部字符串"变得很简单:构建期把目录编译好,运行时 i18n.load 后即可使用。但当应用支持多种语言时,静态 import 所有 locales/*.po / messages.js 意味着首屏要下载所有语言的翻译。
动态加载的思路是:只在需要某个 locale 时才下载它。Lingui 为此做了两点支撑:
i18n实例本身不假设你的应用结构——你不需要在初始化时把所有语言目录一次性传入,I18nProvider组件同样不对应用结构做假设,把"加载哪些消息"的自由留给了应用侧;- 生产构建会刻意"丢弃默认消息"(default message),让 i18n 足迹最小化——这也是下文中"连默认语言也要 load"这一看似反直觉要求的根源。
完整的 Loader Helper:dynamicActivate
指南给出的核心是一个 i18n.ts 辅助文件,它封装了"按需动态加载并激活目录"的全部逻辑:
import { i18n } from "@lingui/core";
export const locales = {
en: "English",
cs: "Česky",
};
export const defaultLocale = "en";
/**
* We do a dynamic import of just the catalog that we need
* @param locale any locale string
*/
export async function dynamicActivate(locale: string) {
const { messages } = await import(`./locales/${locale}/messages`);
i18n.load(locale, messages);
i18n.activate(locale);
}
关键在于 await import(\./locales/${locale}/messages`)` 这一模板字符串动态导入。Webpack/Rspack 等 bundler 会为匹配到的每个模块生成独立的异步 chunk,主 bundle 里不再包含任何翻译文本,这正是后文"每个语言一个 chunk"的来源。
源码印证:load 与 activate 各自做了什么
对照 I18n 类实现 可以看到这两步的精确语义:
i18n.load(locale, messages)(L169-L185)支持两种形态:单 locale 加载(load('en', catalog))和批量加载(load({ en: catalog, cs: catalog }))。单 locale 形态下,若该 locale 已存在目录则做Object.assign合并,否则直接替换;加载完成后emit("change");i18n.activate(locale, locales?)(L199-L209)只切换活动 locale(locales是用于数字/日期格式化的 BCP 47 备选标签列表),不关心目录是否已加载。开发环境下,如果目标 locale 没有已加载的消息,activate会打印警告Messages for locale "xx" not loaded.——这对"忘了先 load 就 activate"的常见错误是一个即时提示;- 此外还有一个组合方法
loadAndActivate({ locale, locales, messages })(L190-L197),它把 locale、messages 一次性写入并触发change事件,可以看作load + activate的原子化版本,适合在加载完目录后一步完成激活。
还有一个容易踩坑的点:i18n._() / t() 在没有任何活动 locale 时会直接抛出异常(L219-L225),错误信息明确提示要先调用 i18n.activate(locale),并指出这可能源于初始化逻辑中的竞态条件——也就是说,dynamicActivate 是异步的,你必须保证"第一次调用翻译"发生在它 resolve 之后。
重要前提:连"默认语言"也要加载目录
指南特别强调(caution):
即使是默认 locale 也必须加载目录。Lingui 通过在生产构建中丢弃默认消息来保持 i18n 足迹最小化,这样只有活动语言的目录会被加载,避免重复。如果没有这个优化,从默认语言(如 EN)切换到另一种语言(如 FR)就需要同时加载两个语言的目录。
这不是文档的臆断,而是实现决定的:
- 生产环境不注册消息编译器。I18n 构造函数 仅在
NODE_ENV !== "production"时调用setMessagesCompiler(compileMessage);一旦翻译值是未编译的字符串,生产环境既没有编译器兜底,插值与复数等 ICU 特性也无法工作(参见 L262-L276 的运行时警告)。因此生产路径假设目录是预编译的——默认消息(descriptor 里的message字段)不在任何 bundle 中; - 运行时翻译回退链是
已加载消息 → message 字段 → id(L258)。当默认消息被裁剪、目录又没加载时,翻译会退化为 message id,界面显示原文 id 而非可读文案。
所以正确的心智模型是:任何 locale(包括默认 EN)的消息都必须显式 i18n.load,一次只加载一个活动语言的目录,切换语言时只新增下载新语言的 chunk。
在应用中使用:React 启动时加载
dynamicActivate 必须在应用启动阶段调用。指南给出的 React 用法:
import React, { useEffect } from "react";
import App from "./App";
import { I18nProvider } from "@lingui/react";
import { i18n } from "@lingui/core";
import { defaultLocale, dynamicActivate } from "./i18n";
const I18nApp = () => {
useEffect(() => {
// With this method we dynamically load the catalogs
dynamicActivate(defaultLocale);
}, []);
return (
<I18nProvider i18n={i18n}>
<App />
</I18nProvider>
);
};
I18nProvider 如何配合"延迟加载"
阅读 I18nProvider 源码 可以解释这段写法为什么安全:
- 在
i18n.locale为空(尚未 activate)时,Provider 直接渲染null,并在开发环境打印一条信息性日志:"A call toi18n.activateneeds to happen in order for translations to be activated and for the I18nProvider to render."(L115-L122)。因此useEffect里异步加载目录期间,界面不会渲染出半初始化的翻译; load/activate触发change事件后,Provider 通过useSyncExternalStore订阅 store 并重建上下文,所有使用useLingui()的组件随之重新渲染(L92-L113)。换句话说,语言切换 UI 无需手动刷新——dynamicActivate(newLocale)返回后界面自动切到新语言。
仓库中 Next.js Babel 示例 展示了另一种真实形态:用 loadCatalog(locale) 动态导入 ./locales/${locale}.po,再交给 setupI18n,思路与 dynamicActivate 完全一致,只是目录来源可以换成 REST API、缓存等任意通道(源码注释明确说明加载函数不属于 Lingui 库本身,因为它有太多种实现方式)。
优化后的 Bundle 结构:每个语言一个 chunk
按上面的方案构建后,产物目录中每个语言对应一个独立 chunk:
i18n-0.c433b3bd.chunk.js
i18n-1.f0cf2e3d.chunk.js
main.ab4626ef.js
请求时序如下(对应文首两张 DevTools 截图):
- 首次加载页面:只请求
main包 + 首个语言(如 en)对应的i18n-*chunk。此时useEffect触发dynamicActivate(defaultLocale),加载完成后 Provider 才渲染应用; - 用户切换语言:再请求目标语言(如 cs)的 chunk,加载并 activate 后界面自动刷新;其余语言的 chunk 始终驻留在磁盘/CDN,永不下载。
这样,支持 N 种语言的应用,首屏 i18n 开销恒定为"1 个语言目录",而不是 N 个。
配套能力:Dependency Tree Extractor(实验特性)
动态加载解决的是"运行时少下载",而提取阶段若仍用单一 glob 把全项目消息扫进一个大目录,每个 chunk 里依然可能塞着该页面根本用不到的消息。指南最后提到的 Dependency Tree Extractor(experimental feature)就是针对提取端的对应方案:
- 它不用 glob 扫目录,而是从入口文件出发沿依赖树爬取 import,用 bundler 的 tree-shaking 结果决定每个入口真正用到哪些消息,从而为每个组件/页面生成"更小、更相关"的目录;
- 对 Next.js 这类多页面应用尤其有用——glob 方式下每个页面都会携带全部消息,而依赖树方式让目录粒度与路由粒度对齐。
配置方式(详见 Message Extraction 指南):
module.exports = {
catalogs: [], // 清空 catalogs
experimental: {
extractor: {
// 入口 glob,例如找到所有 Next.js 页面
entries: ["<rootDir>/src/pages/**/*.tsx"],
// 输出模式:src/pages/faq.tsx -> src/pages/locales/faq/en.po
output: "<rootDir>/{entryDir}/locales/{entryName}/{locale}",
},
},
};
然后执行:
lingui extract-experimental
从源码结构看,该特性的实现位于 packages/cli/src/extract-experimental/:getExperimentalCatalogs.ts 用 globSync(config.entries) 展开入口,再对每个入口按 output 模板解析出各自的 catalog 路径(resolveCatalogPath),最终每个入口产出一个独立 Catalog;bundling、chunk 图构建(buildChunkGraph.ts)、按 chunk 提取(extractFromChunk.ts)与写盘(writeCatalogs.ts)构成完整管线。需要留意文档的边界说明:这是实验特性,不受 semver 保护,可能随版本变化,且目录的准确程度依赖你的代码是否可被 tree-shake(例如带副作用的消息定义可能需要 /* @__PURE__ */ IIFE 包裹才能被正确剔除)。
小结
- 用
dynamicActivate(locale)(动态import+i18n.load+i18n.activate)实现运行时按需加载,React 侧在useEffect中于启动时调用即可; - 记住两个硬约束:默认语言也必须显式 load(生产构建裁剪了默认消息),以及翻译前必须先 activate(否则
i18n._直接抛错,Provider 也渲染null); - 产物上验证收益最直接:build 目录中每个语言一个
i18n-*.chunk.js,首屏只下载 main + 当前语言; - 想进一步压缩每个目录的体积,可尝试
experimental-extractor的依赖树提取,让提取粒度与页面/路由对齐。

