排查 React 消息问题

定位消息从提取到渲染的过程中,在哪个环节丢失了翻译、值、标签或语言区域。

从屏幕上实际显示的消息入手。消息的源文本和上下文决定使用哪个键;最近的提供器提供消息目录;选中的模板则用调用时传入的值进行格式化。检查这些输入,通常就能定位问题,无需手动修改生成的键。

useLingo 在提供器外部抛出异常 #

将 LingoProvider 放在调用钩子的组件上层,测试和独立预览中也应如此。同一组件返回的提供器位于该钩子的下层。将钩子移到子组件中,或在不通过 React 上下文渲染的函数中使用 createLingo(locale, messages)。

当前的提供器实现需要使用 React 19。它采用了 React 19 的上下文简写语法;该包声明的对等依赖版本范围虽然更宽,但并不会让这一语法兼容 React 18。

显示源文本而非译文 #

  1. 检查最近的提供器实际使用的 locale 和 messages。消息必须是从哈希到字符串的映射,不能是文件 URL、Promise 或 LocaleFile。
  2. 根据实际调用的完整内容计算 computeKey(source, context),然后在传入的映射中查找该键。标点、空白字符或上下文的变化,都可能产生新的标识。
  3. 如果提取结果中缺少该键,请使用字面量形式的源文本和上下文,通过受支持的接收对象(例如 l.text(...))调用,然后重新运行提取。动态计算的调用可以在运行时渲染,但未必能被提取。
  4. 如果源消息目录中有该键,而目标消息目录中没有,请获取已完成的翻译并重新加载映射。仅完成提交并不会将文件放入应用中。
  5. 如果文件中有该键,而提供器中没有,请检查加载器的路径和路由选择。消息目录加载介绍了翻译后的 JSONC 丢失元数据时所需的源键关联操作。

值缺失或为空字符串时,都会回退到源文本。开发环境中的警告会区分这两种情况,并按键和语言区域去重。生产环境不会输出这些诊断信息,因此控制台没有输出,并不能证明消息目录完整。

Next 加载器在文件缺失时返回 {},但遇到格式错误的 JSONC 时可能抛出异常。TanStack 的内置消息目录会将文件缺失、加载失败和解析失败统一处理为 {},并缓存该结果。无论哪种情况,回退到源文本都能让页面保持可读,但也可能掩盖加载问题。

占位符或 ICU 表达式仍然可见 #

检查调用实际收到的 values 对象。缺少简单占位符的值时,{name} 会原样显示。如果没有传入值对象,运行时会直接返回选中的模板,不进行格式化。

对于复杂的 ICU 消息,请检查选中的目标模板的语法、参数名和值类型。解析或格式化出错时,运行时会返回该模板,并输出经过去重的开发环境错误信息。因此,页面可能显示格式错误的译文,而不是英文源文本。修复模板或补上缺少的参数,然后重新渲染该场景。

生成的声明可以检查已检测到的源文本参数,但既不会验证目标模板的语法,也无法发现嵌套在 ICU 分支中的所有占位符。请使用真实值测试受影响的分支。

富文本消息使用命名回调,例如 tags.link。回调名称必须与译文中的标签名完全一致,链接目标也应保留在回调中。未知的成对标签、自闭合标签以及未闭合的起始标签都会原样显示为文本。

为嵌套元素使用不同的名称。解析器不支持同名标签重复嵌套的结构。富文本消息支持简单占位符,不支持完整的 ICU 语法;需要使用 ICU 语法时,请使用文本语法辅助工具。富文本介绍了受支持的形式。

URL 变了,但语言没变 #

同时替换语言区域和消息目录。仅更新语言区域,可能会导致法语文本按西班牙语规则格式化。还应检查嵌套的提供器:使用不同语言区域的子提供器是独立的,不会继承父提供器的消息目录。

使用所选适配器的切换器。Next Pages 使用路由导航和语言区域 Cookie。TanStack 使用普通锚点链接,以便通过新请求加载新的消息目录。

水合期间文本、书写方向或日期发生变化 #

对比服务端和客户端的输入:消息目录版本、语言区域、值、时间戳、时区以及相对时间的基准。在框架外壳中设置文档的 lang 和 dir;基础提供器不会修改它们。然后按照服务端渲染检查清单测试初始 HTML 和水合后的页面。