迁移现有 React 消息
将一小组 React 消息测试样例迁移为显式声明源文本和上下文的消息,保留占位符、复数行为及已认可的译文。
现有 React 消息目录中已经沉淀了有价值的设计决策:查找标识、插值规则、复数行为,以及经过审核的译文。迁移为基于源文本和上下文的消息时,应保留这些成果。先转换一个完整组件,将其已认可的译文映射到新标识,再对比渲染结果,确认后再扩大迁移范围。
更改标识前,记录原有行为 #
选择一个包含标签、变量、链接、计数和条件消息的组件。保存原有的键、源文本和目标译文、插值语法、命名空间,以及提供器的语言区域。使用固定值,分别以源语言和一种目标语言渲染组件,为迁移建立一个需要保留的具体结果。
例如,现有的 i18next 风格调用可能如下:
t("account.greeting", { name });其源消息目录可能包含 Welcome, {{name}}。不要将这套插值语法原样复制到新的消息契约中。显式声明的 React 消息使用具名的 {name} 变量:
l.text("Welcome, {name}", {
context: "Greeting on the signed-in account page",
values: { name },
});此处的分隔符变更仅适用于这一源库配置。转换其他消息前,请先检查已安装的库:自定义插值分隔符和复数约定可能需要采用不同的修改方式。
映射消息行为,而不只是方法名称 #
带有值的普通消息使用 text,具名组件插槽使用 rich,随计数变化的形式使用 plural,按精确值选择的备选项使用 select,并以 other 作为回退。富交互消息提供了涵盖这四种用法的完整示例。
旧的富文本消息组件可能通过索引表示链接。请将这些索引替换为含义明确的具名插槽,并将链接目标保留在代码中。同时保留变量的名称、类型和语义角色。旧的复数消息目录可能通过带后缀的键存储消息;新的运行时则根据各个形式构建复数消息。请验证目标语言的实际行为,而不是机械地重命名后缀键。
选择能说明消息用途的上下文。新标识由源文本和上下文生成,而不是由 account.greeting 生成。维护一张迁移表,记录旧键、语言区域、提取出的新键,以及任何语法转换。问候语对应的那一行应记录从 {{name}} 到 {name} 的转换。借助这张映射表,审核者可以追踪已认可的译文在新消息目录中的对应位置,并查看哪些消息尚未映射。
有计划地提取并导入小型消息目录 #
安装 @lingo.dev/react,并按照React 快速入门配置 LingoProvider。当前的提供器实现请使用 React 19;即使其声明的对等依赖版本范围包含 React 18,也不能替代对旧版应用的测试。转换组件后,运行已安装的 CLI:
lingo extract --src src --source-locale en如果未覆盖路径配置,请检查 locales/en.jsonc 和 lingo.d.ts。找到每条源消息及其上下文,将实际提取出的键复制到迁移表中。沿用旧键或自行编造哈希值,会使目标译文与运行时查找脱节。
将每条已认可的目标译文放到映射得到的新键下。仔细转换占位符、富文本插槽和复数语法,同时保留原意。通过消息目录加载工作流加载哈希值到字符串的目标映射;缺少目标元数据时,使用对应源消息中的有效键。让未映射的条目继续作为待办事项清晰可见,不要将其归类为已废弃。
将请求的语言区域及其目标消息一起传给 LingoProvider。在渐进式迁移期间,保留新旧提供器,让它们分别包裹各自的调用方。提供器契约说明了同一语言区域的合并和不同语言区域的隔离;迁移嵌套页面时,请核查这些行为。
验证消息缺失和格式错误的情况 #
使用与迁移前相同的值渲染测试样例。对比可见内容的含义、变量位置、链接行为、复数输出和回退选择。测试应涵盖零、一和更大的计数值、较长的变量值,以及未知的选择值。
在本地测试样例中移除一条目标条目,检查是否回退到源文本。消息缺失或为空时,仍可能渲染源文本,因此页面可用并不代表目标译文已完全覆盖。运行提取一致性检查和 TypeScript 检查,确保检查范围包含生成的声明,然后运行应用现有的渲染测试。类型只能确认调用兼容性,不能保证翻译质量。
遇到格式错误的富文本标签或 ICU 消息时,请检查输出和诊断信息。新的运行时可能直接显示原样的标记或未经格式化的模板,因此在移除旧运行时之前,请对照应用要求评估这种行为。React 故障排查说明了这些限制。
将智能体辅助成果纳入审核流程 #
请智能体检查现有库、保留键映射、识别不支持的模式,并将源代码修改与消息目录导入分开处理。应用其提出的源代码和消息目录更改之前,请先进行审核。
测试样例通过渲染检查和原生检查后,再按组件或命名空间扩大迁移范围。保留新旧两个消息目录,直到每个调用方和每条已认可的目标译文都已确认新的对应位置。只有在没有任何代码继续使用旧提供器和依赖时,才将它们移除。API 客户端和路由适配器各有职责;更换消息运行时并不能替代它们。