本地化 Web 应用

将翻译后的消息目录接入框架的语言区域选择、资源加载与渲染检查流程。

如果你的 Web 应用已经从语言区域文件中加载并渲染消息,请沿用这套方式。Lingo.dev 可以负责翻译源消息目录,现有库则继续负责选择语言区域、加载和渲染消息。在翻译应用的其余部分之前,先在一个页面上跑通完整流程。

本指南适用于各类框架中现有的键值消息目录。如果使用 @lingo.dev/react 处理源文本与上下文消息,请参阅 React 快速入门或迁移指南。它提取的消息标识与现有 i18next 或 next-intl 消息目录中的键不同。

建立一个端到端测试样例 #

选择一个包含标签、带变量的消息,以及复数或条件消息的页面,通过现有库以源语言渲染。保留原有的命名空间、插值语法和查找键;通用 JSON 翻译不会将一个库的消息语法转换成另一个库的语法。

如果现有 react-i18next 源文件位于 public/locales/en/translation.json,请在项目根目录初始化 CLI:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'public/locales/en/translation.json' --yes
lingo link

关联后的 .lingo/config.json 应具有以下结构:

json
{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es"],
  "files": [{ "pattern": "public/locales/en/translation.json" }]
}

保留关联时生成的实际组织 ID 和本地化引擎 ID。如果使用其他框架,请替换为下方对应章节中的源路径。只选择源消息目录,并确保目标路径与加载器匹配。如果目录布局不含语言区域路径段,请使用显式目标路径。

使用以下命令翻译缺失的目标文件:

sh
lingo push --backfill-missing --wait

完成后,检查生成的消息目录,并以西班牙语加载页面。使用相同的变量值和复数情形,对比两种语言的表现。下方各框架的操作步骤会将该文件接入实际请求或构建流程。首次普通推送可以保存基线,而不请求补齐缺失的翻译。

等待回写执行期间,请勿改动目标文件。如果需要保护现有的本地修正,避免冲突,请在提交时省略 --wait,检查 lingo pull --dry-run,再从提交时使用的 checkout 中取回结果。参阅保留已审核的翻译。

React 与 react-i18next #

使用 react-i18next 时,请保留现有的命名空间和查找调用。位于 public/locales/en/translation.json 的源文件映射到 public/locales/es/translation.json。如果应用使用多个命名空间,请逐一配置英语源文件,不要使用会同时匹配生成的西班牙语文件的通配模式。

让 i18next 资源加载器请求目标语言区域和命名空间,再使用现有的 useTranslation 调用渲染测试样例。检查变量替换,以及当前安装的 i18next 版本所采用的复数键约定。通用 JSON 翻译器不会将一个库的复数结构转换成另一个库的结构。在客户端应用中,除了可见文本,还要检查资源的网络请求;英语回退可能掩盖西班牙语文件缺失的问题。

Next.js App Router 与 next-intl #

使用 next-intl 时,常见的源文件是 messages/en.json,对应生成 messages/es.json。在 next-intl 配置中设置请求时的语言区域解析,并加载匹配的消息。确保语言区域相关的路由和导航与所选语言区域一致。

分别通过直接请求目标语言区域,以及从其他语言区域导航过来的方式渲染测试样例。检查服务端渲染内容、客户端水合,以及 ICU 变量或复数。仅翻译消息文件,并不会添加 App Router 语言区域路径段或语言切换器。如果这些 UI 消息目录还配有长篇文档,请使用 Markdoc 与 Next.js。

Next.js Pages Router 与 next-i18next #

使用 next-i18next 时,请设置源文件匹配模式,使其匹配现有的语言区域目录和命名空间。如果源文件为 public/locales/en/common.json 和 public/locales/en/checkout.json,请将两者翻译为对应的西班牙语文件。如果使用 messages/en.json,请保留实际读取它的自定义加载器。

通过页面现有的服务端或静态数据加载流程,加载所需的命名空间。验证直接请求本地化页面和客户端路由切换这两种情况。检查初始页面数据与客户端运行时使用的语言区域和命名空间是否一致;如果页面从未包含翻译文件,仅在磁盘上保存该文件还不够。

Vue 与 vue-i18n #

vue-i18n 可以加载 src/locales/en.json 和 src/locales/es.json 等字典。翻译英语源文件,并在现有 i18n 实例中注册或动态加载西班牙语字典。在应用原本管理语言区域的位置设置所选语言区域。

在测试样例中测试 $t 或 useI18n 调用。检查嵌套键、插值,以及当前安装的库所采用的复数消息语法。分别测试无需重新加载页面的语言区域切换,以及重新加载页面的情况。如果字典通过导入打包,请确认构建产物包含翻译后的文件。

Nuxt 与 i18n 模块 #

使用 Nuxt i18n 时,请将 locales/en.json 等源文件翻译为 locales/es.json。按照当前安装版本的要求,在模块配置中注册语言区域和文件。确保配置的语言目录与 CLI 输出路径一致。

沿用项目现有的语言区域路由策略,不要在翻译任务中另建一套。在测试样例页面上验证服务端渲染、懒加载、本地化导航和元数据。在翻译配置中添加目标语言区域,并不会自动将其加入 Nuxt 的语言区域列表。

Svelte 和 SvelteKit 字典 #

使用 svelte-i18n 时,请翻译 src/lib/locales/en.json 等字典。注册目标字典或其懒加载器,并在组件需要使用它之前初始化所选语言区域。

通过应用现有的翻译状态存储渲染测试样例。如果应用使用 SSR,先测试一次新的服务端渲染请求,再测试客户端语言区域切换。确认不同服务端请求之间的语言区域状态相互隔离,且目标字典已完成加载。不要把回退输出当作翻译已完成的证明。

Angular XLIFF #

先使用 Angular 的 i18n 工作流标记并提取消息。XLIFF 处理器支持 XLIFF 1.2 和 2.x,包括纯文本和内联代码。<g> 和 <pc> 等成对代码中的文本会被翻译,代码结构则保持不变;<ph> 等独立代码会受到保护。请保持消息和内联代码的标识符稳定,并在导入目标消息目录前检查返回的占位符。

对于受支持的输入,src/locale/en/messages.xlf 映射到 src/locale/es/messages.xlf。XLIFF 不使用从 messages.en.xlf 到 messages.es.xlf 的后缀替换方式;请使用语言区域目录或显式目标模板。将翻译导回 Angular 时,请保留消息标识。

在 Angular 的本地化构建配置中注册目标文件,构建目标语言区域的资源包,再通过服务加载并检查页面。Angular 的编译时本地化不同于运行时 JSON 加载器:更改浏览器语言区域,并不会构建缺失的本地化资源包。验收资源包前,请检查消息覆盖情况和占位符渲染。

Astro #

对于 UI 标签,请将 src/i18n/en.json 翻译为对应的目标文件,并让自己的字典加载器选择该文件。对于内容集合,请翻译各语言区域对应的 Markdown 或 MDX 源文件,并使用静态内容工作流。

请独立于翻译流程配置 Astro 的语言区域路由。构建并访问生成的目标路由,检查不同语言区域版本之间的链接,以及自行加载消息的客户端岛组件。内容集合与岛组件的 UI 字典可能需要分别提供输入。

Laravel #

使用 Laravel 本地化 时,lang/en/messages.php 等 PHP 源文件映射到 lang/es/messages.php。请保留数组键和运行时替换参数名。如果文件中的可执行代码超出受支持的消息目录结构,请在选择文件前查阅 PHP 格式参考。

通过应用现有的中间件或控制器策略设置请求语言区域,并使用 Laravel 的翻译辅助函数渲染消息。测试替换值和复数选择。为每个受支持的语言区域测试一次请求,并测试一种回退情形;翻译文件本身不会为请求选择语言区域。

Django #

使用 Django 的提取工作流创建 locale/en/LC_MESSAGES/django.po,再将该源 PO 文件翻译到目标语言区域目录。保留 gettext 消息标识、上下文和插值。通过项目现有的 gettext 构建步骤,将翻译后的 PO 编译为 Django 实际加载的资源。

配置 Django 的语言选择和语言列表。通过翻译中间件验证本地化请求,并渲染单数和复数调用。磁盘上存在 PO 文件,并不代表其编译后的消息目录已更新。文件规范请参阅 Gettext。

Rails #

Rails 通过根键识别以语言区域为根键的 YAML 文件。选择 yaml-root-key,然后验证 Rails 的语言区域配置、辅助函数和插值。本地化 Rails 应用介绍了完整流程,包括按功能拆分文件、切换请求语言区域,以及限定范围的更新。

让持续翻译产出便于审核的结果 #

页面正常运行后,添加其余源消息目录及其加载器。将已接受的目标文件与源文件版本和 CLI Lockfile 一起保留。后续源文件变更使用 lingo push --wait 处理常规增量;以位置参数传入文件匹配模式,则会采用限定范围的规划。

通过 GitHub App 或 CI 配置方案选择源文件变更的触发方式和回写方式。GitLab、Bitbucket 和 GitHub Actions 配置方案会运行 CLI,仓库回写需要另行配置。对输出执行框架的构建或资源检查,再审核翻译后的含义。lingo check 不会验证所有框架,也不会确认 PHP、PO 或 XLIFF 的完整性。

智能体可以帮助检查加载器,并提出配置修改建议。扩展工作流之前,请对这些修改执行同样的源文件选择、构建和页面渲染检查。