本地化富文本交互消息

翻译完整句子,同时由 React 代码掌控其中的链接、组件和值。

“继续之前,请阅读政策”是一整句话,即使其中的“政策”是一个链接。将整句话作为一个翻译单元,其他语言就能把链接移到合适的位置,同时仍由应用代码控制链接的目标地址。

React 包的 rich 方法将这个链接表示为具名插槽。消息目录提供句子,React 渲染器则为插槽提供组件。

渲染包含链接的完整句子 #

在现有的 React 19 应用中安装 @lingo.dev/react。这个本地示例使用演示用的西班牙语消息目录,无需发起翻译请求:

sh
npm install @lingo.dev/react
tsx
import { computeKey, LingoProvider, useLingo } from "@lingo.dev/react";

const messages = {
  [computeKey(
    "Read the <policy>policy</policy> before continuing.",
    "Notice before account creation",
  )]: "Antes de continuar, lee la <policy>política</policy>.",
};

function ConsentNotice() {
  const l = useLingo();
  return (
    <p>
      {l.rich("Read the <policy>policy</policy> before continuing.", {
        context: "Notice before account creation",
        tags: {
          policy: (children) => <a href="/policy">{children}</a>,
        },
      })}
    </p>
  );
}

export function App() {
  return (
    <LingoProvider locale="es" messages={messages}>
      <ConsentNotice />
    </LingoProvider>
  );
}

该段落应显示为“Antes de continuar, lee la política.”。译文调整了政策引用的位置,但链接仍指向 /policy。调用中的源文本字面量和上下文也能让这条消息在提取时被识别。computeKey 会构建测试数据的真实标识,而不是依赖编造的哈希值。

虽然该包声明的对等依赖支持 React 18/19,但提供器目前使用的是 React 19 上下文语法。请单独验证 React 18。React 快速入门介绍了提供器的设置方法,以及如何准备第一个消息目录。

将值和行为保留在代码中 #

policy 标识的是一个插槽,而不是翻译人员提供的 HTML 元素。链接的目标地址和行为由该插槽的渲染器控制。请在代码中通过已知的路由映射确定特定语言区域对应的目标地址;不要将事件处理函数和任意 HTML 属性放入消息目录。

对于会变化的值,请使用具名占位符:

tsx
const greeting = l.text("Welcome, {name}", {
  context: "Greeting on the signed-in account page",
  values: { name },
});

const countLabel = l.plural(
  count,
  { one: "# item", other: "# items" },
  { context: "Number of items in the cart" },
);

const roleLabel = l.select(
  role,
  { admin: "Administrator", other: "Member" },
  { context: "Account role label" },
);

这些调用应放在组件内部,并使用 const l = useLingo() 以及应用中对应 name、count 和 role 的值。text 返回纯文本,plural 处理随数量变化的语法,select 匹配精确的选择器,并以 other 作为回退。富文本处理支持具名标签和简单的值插值,但不会运行纯文本处理所用的复杂 ICU 格式化器。对于这些运行时判断,请使用复数、日期和数字。

保持源文本静态不变。将人名放入源字符串,会为每个人生成不同的源文本,导致提取无法可靠进行。上下文应说明消息的用途,例如“账户角色标签”,因为源文本和上下文共同决定消息的标识。已有译文后,请慎重修改上下文。

用提取的消息目录替换本地测试数据 #

安装当前版本的 CLI 后,运行:

sh
lingo extract --src src --source-locale en

如果未覆盖默认路径,这会写入 locales/en.jsonc 和 lingo.d.ts。请检查提取出的源文本、上下文和键,并在应用的 TypeScript 配置中包含该声明。提取支持可识别的消息调用,但无法发现任意动态生成的源字符串。

按照 CLI 快速入门完成身份验证并关联本地化引擎,然后在 .lingo/config.json 中选择实际使用的 locales/en.jsonc 源文件和所需的目标语言区域。通过该文件工作流完成翻译并获取消息目录。按照消息目录加载流程解析 JSONC,从匹配的源版本中选择有效键,并将目标字符串传入提供器。通用文件翻译器不会在目标输出中保留源消息目录的注释。

使用获取到的西班牙语消息目录加载同一条提示。缺失或为空的条目会回退到源文本,因此除了检查可见输出,还应比对所需的目标键。

测试交互及格式错误的情况 #

使用键盘打开政策链接,并检查其无障碍名称。链接位置变化后,阅读其周围的标点。完整的译文必须既保留句子的含义,也保留读者可执行的操作。

在本地消息目录测试数据中,移除标签处理函数、引入未知标签,并让一个标签保持未闭合状态。当前渲染器会将未知或未配对的标记保留为文本;同名标签嵌套时,配对能力有限。它既不是用于渲染任意 HTML 的渲染器,也不是会拒绝所有格式错误消息的验证器。

对于纯文本,请检查值缺失和复杂 ICU 消息格式错误的情况:未解析的占位符或未格式化的模板可能仍会显示,并伴随开发诊断信息。对于数量和角色消息,请测试目标语言的复数类别和未知角色。有关这些检查涉及的具体行为,请参阅富文本参考和 React 测试指南。