富文本消息

翻译完整句子,同时将链接目标和 React 行为保留在应用代码中。

链接往往是句子的一部分。将链接前、链接内和链接后的文字分别翻译,会迫使译文沿用源语言的语序。l.rich 让整个句子可以一起翻译,并由译文模板将具名 React 元素放到合适的位置。

让句子保持完整 #

tsx
import { useLingo } from "@lingo.dev/react";

export function PurchaseNotice({ product }: { product: string }) {
  const l = useLingo();
  return (
    <p>
      {l.rich("Read the <link>refund policy</link> before buying {product}.", {
        context: "Purchase notice linking to the refund policy",
        values: { product },
        tags: {
          link: (children) => <a href="/refund-policy">{children}</a>,
        },
      })}
    </p>
  );
}

在 提供器 下渲染此组件。源文本和上下文用于选择翻译目录中的条目,方式与 l.text 相同。译文模板控制文字内容和标签位置;回调则提供链接目标、属性、样式和行为。

l.rich 返回一个 ReactNode。其 RichOptions 必须提供 context,可接受值为字符串或数字的 values 映射,也可接受 tags: Record<string, (children: ReactNode) => ReactNode>。标签名称必须完全匹配,因此 <link> 需要对应的 link 回调。

插入不含子元素的元素 #

自闭合标签调用渲染器时,传入的子元素为 null。例如,下面的确认消息会在消息文字后放置一个装饰性图标:

tsx
const confirmation = l.rich("Saved <icon/>", {
  context: "Confirmation that account settings were saved",
  tags: {
    icon: () => <span aria-hidden="true">✓</span>,
  },
});

这里的 l 是组件的 useLingo() 结果。<icon/> 和 <icon /> 都受支持。嵌套元素需要使用不同的名称,例如 <link><strong>refund policy</strong></link>,并提供两个回调。解析器会使用下一个匹配的闭合标签;不支持将同名标签重复嵌套为配对完整的 HTML 结构。

检查译文中的文字,也别忘了标签 #

成对标签或自闭合标签没有对应回调时,会作为文本原样保留。没有匹配闭合标签的起始标签也会如此。这样消息仍可渲染,但读者可能看到的是 <link>,而不是可用的链接。

请使用实际回调测试译文模板。对链接文字和 href 进行断言,并加入缺少标签的测试用例,以便在开发过程中发现意外出现的标记。渲染测试无需发起翻译请求。

支持的标记仅限具名标签,不支持任意 HTML。请在回调中设置属性,不要将属性写入译文。使用 dangerouslySetInnerHTML 处理未匹配的标签,会破坏这种分离。

在富文本消息中使用简单值 #

富文本会替换文本片段中的简单 {name} 值,但不会运行 l.text 所使用的复杂 ICU 格式化器。对于随数量变化的语法,请使用复数和选择表达式,或使用语法完整、且能通过受支持的富文本形式表达的消息来组织界面。直接写在富文本模板中的 ICU 复数表达式,不会仅因包含大括号就具备复数处理功能。