lingui-framework-setup

Lingui 框架设置

Lingui 的正确设置取决于所用框架：在 Vite SPA 中可行的做法，在 React Server Components 中可能失效；而在浏览器中没有问题的模块级 i18n 单例，在 SSR 下会导致不同请求之间的语言环境相互污染。本指南将引导你采用框架原生方案，而非泛泛地回答「使用 I18nProvider」。

请按以下顺序操作：检测技术栈 → 应用通用步骤 → 遵循框架参考 → 执行验证流程。

第 1 步 — 检测技术栈

在提出建议前，先查看 package.json 和构建配置。切勿猜测编译器——如果宏转换配置错误，它会静默失效。

信号	技术栈	参考
依赖中有 next，且存在包含 layout.tsx 的 app/ 或 src/app/	Next.js App Router	nextjs-app-router.md
依赖中有 next，存在包含 _app.tsx 的 pages/，且没有 app/	Next.js Pages Router	Lingui 支持此模式，简要说明见 nextjs-app-router.md
依赖中有 @tanstack/react-start	TanStack Start（SSR）	tanstack-start.md
devDeps 中有 @react-router/dev，且存在 react-router.config.*	React Router 7 框架模式（SSR）	react-router-remix.md
devDeps 中的 @remix-run/dev ≥ 2.7，且有 vite	Remix v2（Vite 构建，SSR）	react-router-remix.md
有 vite 和 react，且不符合以上任何一项	Vite SPA（包括声明式 React Router、TanStack Router）	vite-spa.md

宏转换（决定要安装什么）。对于所有 Vite 技术栈，无论使用哪个 React 插件，默认都采用 @lingui/vite-plugin 6.9.1+ 中的原生转换；Vite 编译器对应的行是备用方案，适用条件见 vite-spa.md：

信号	编译器	宏转换
任意 Vite 技术栈	无需	lingui({ macroTransform: true })
@vitejs/plugin-react-swc	SWC	@lingui/swc-plugin（固定精确版本——参见 swc-plugin-compatibility 技能）
@vitejs/plugin-react ^5 或更低版本	Babel	通过插件的 babel 选项使用 @lingui/babel-plugin-lingui-macro
@vitejs/plugin-react ^6+，Vite 8	Babel，独立处理流程	v6 移除了 babel 选项——将宏作为独立处理流程运行：@rolldown/plugin-babel + linguiTransformerBabelPreset()。保留原版 React 插件
@vitejs/plugin-react ^6+，Vite ≤ 7	Babel，独立处理流程	同上，使用 vite-plugin-babel（不使用 Rolldown）。也可以切换到 @vitejs/plugin-react-swc，但需要固定精确版本
Next.js，且没有 .babelrc	SWC	通过 experimental.swcPlugins 使用 @lingui/swc-plugin
使用 .babelrc 的 Next.js	Babel	在 .babelrc 中配置 @lingui/babel-plugin-lingui-macro（Babel 配置会禁用 Next 的 SWC）

还有一个会彻底改变结论的区别：依赖中有 react-router，但没有 @react-router/dev，说明这是一个声明式 SPA（在 JSX 中使用 <Routes>）——应参考 Vite SPA，而非框架模式。写入声明式 SPA 的路由模块 loader/+types 代码一开始就无法运行。

第 2 步 — 通用步骤（适用于每种框架）

版本门槛。 当前版本为 Lingui 6：仅支持 ESM，要求 Node ≥ 22.19（或 ≥ 24）。安装 @lingui/core@^6 @lingui/react@^6，并将 @lingui/cli@^6 作为开发依赖。如果项目无法满足 Node 版本要求，则将所有 @lingui/* 软件包固定为 ^5——不要混用主版本。不要安装 @lingui/macro：从 v5 起，宏位于 @lingui/react/macro 和 @lingui/core/macro 中。

各技术栈的额外依赖（详情见各参考文件）：

技术栈	额外运行时依赖	额外开发依赖
Next.js App Router	—	@lingui/swc-plugin（精确固定版本）
Vite SPA	@lingui/detect-locale	@lingui/vite-plugin（也会转换宏）
React Router 7 / Remix	—	@lingui/vite-plugin（也会转换宏）、@lingui/format-po
TanStack Start	—	@lingui/vite-plugin（也会转换宏）

@lingui/detect-locale 仅限浏览器使用（navigator、localStorage、window.location）。绝不要在 SSR 技术栈中安装它——它会在服务器上抛出错误或导致 hydration 不同步；SSR 技术栈应改为从请求（cookie / Accept-Language）解析语言区域。

配置和目录。 创建 lingui.config.ts，配置 sourceLocale、locales 和一个 catalogs 条目；lingui-best-practices 技能负责目录管理规范（构建脚本配置、gitignore 规则、CI 漂移检查）和单一来源的语言区域模块（包含 resolveLocale、getDirection、localeDisplayName 的 locales.ts）——请复用这两者，不要重新推导。

两种目录加载模式。 对于基于 Vite 的技术栈，@lingui/vite-plugin 会在导入时编译 .po——await import('./locales/en/messages.po') 可直接使用，无需编写脚本处理或将编译产物加入 gitignore。Next.js 没有 Vite 流水线：在 dev/build 脚本前加上 lingui compile，并导入编译后的目录（@lingui/loader 仅支持 webpack，而 Turbopack 是 Next 15/16 的默认选项，因此基于 loader 的配置是个陷阱）。

第 3 步 — 框架参考

编辑项目之前，请完整阅读对应的参考文件。每份参考文件都按相同顺序遵循以下章节约定：

软件包 → 构建工具集成 → lingui.config → 语言区域解析 → Provider/布局配置 → 路由策略 → 语言切换器 → 注意事项 → 验证

如果项目需要带语言区域前缀的 URL，每份参考文件都提供相同的三种策略——源语言区域不加前缀、所有语言区域都加前缀，或 URL 不包含语言区域（仅使用 cookie/存储）。调整路由结构影响较大：移动文件前，请先询问用户想采用哪种策略。

第 4 步 — 验证

按以下顺序运行；每一步都必须通过后才能进行下一步：

npx lingui extract --clean   # catalogs regenerate; count matches expectations
npx lingui compile           # only on stacks with compiled catalogs (Next.js)
npx tsc --noEmit             # types resolve, incl. catalog imports
npm run build                # macro wiring errors surface here

然后验证转换确实运行了。 构建成功并不能证明这一点：配置错误的宏转换会静默地不起作用，应用最终会以源语言发布。在非源语言目录中翻译一条字符串，以该语言运行应用，并确认浏览器中显示了译文（每份参考文件都提供对应技术栈的具体检查方式——SSR 技术栈使用 curl 检查服务器渲染的 HTML，SPA 则直接加载深层链接）。只有实际看到译文，才算完成配置；构建成功并不够。

此时如果看到原始的未翻译文本，说明是编译器配置问题——插件错误、SWC 条目仅包含裸字符串，或 @vitejs/plugin-react@6 的 babel 陷阱；请参阅 swc-plugin-compatibility 技能。使用原生转换时，缺少 macroTransform: true 不会静默失败：未转换的宏导入会在浏览器中抛出“being executed outside the context of compilation”错误。

添加新框架

新增一种技术栈（新的元框架、新的构建工具）只需修改两处：在第 1 步的检测表中新增一行，并在 references/ 下新增一个遵循第 3 步章节约定的文件。框架特有的信息放在参考文件中；适用于所有技术栈的内容——版本门槛、两种目录加载模式、SSR 的 detect-locale 规则——则保留在这里，只陈述一次。每条不明显的规则都要附上一句原因。

相关技能

• lingui-best-practices — 宏的选择、目录规范和共享区域设置模块。本技能以此为前提；请勿重复介绍。
• swc-plugin-compatibility — SWC 插件版本锁定，以及转换配置错误导致的静默失败模式。
• migrate-i18next-to-lingui — 如果项目已使用 i18next，请先迁移，然后再回到此处配置框架。