Lingui 动态加载消息目录:用 i18n.load 按需加载,砍掉首屏多余的语言包

原创2026-10-09 12:09:471,948 阅读
文章标签:开发工具前端

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)就需要同时加载两个语言的目录。

这不是文档的臆断,而是实现决定的:

  1. 生产环境不注册消息编译器。I18n 构造函数 仅在 NODE_ENV !== "production" 时调用 setMessagesCompiler(compileMessage);一旦翻译值是未编译的字符串,生产环境既没有编译器兜底,插值与复数等 ICU 特性也无法工作(参见 L262-L276 的运行时警告)。因此生产路径假设目录是预编译的——默认消息(descriptor 里的 message 字段)不在任何 bundle 中;
  2. 运行时翻译回退链是 已加载消息 → 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 to i18n.activate needs 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 截图):

  1. 首次加载页面:只请求 main 包 + 首个语言(如 en)对应的 i18n-* chunk。此时 useEffect 触发 dynamicActivate(defaultLocale),加载完成后 Provider 才渲染应用;
  2. 用户切换语言:再请求目标语言(如 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 的依赖树提取,让提取粒度与页面/路由对齐。
登录后查看全文
js-lingui