消息与上下文

编写完整的源消息,说明其含义,并在保持消息标识不变的前提下插入动态值。

要让译文保留文字所表达的操作或含义,消息就需要包含足够的信息。请编写完整的源文本,在 context 中说明其用途,并通过 values 提供姓名、数量等动态数据。

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

export function Greeting({ name }: { name: string }) {
  const l = useLingo();
  return (
    <h1>
      {l.text("Welcome back, {name}.", {
        context: "Greeting at the top of the account dashboard",
        values: { name },
      })}
    </h1>
  );
}

返回结果是字符串。TextOptions 必须提供 context: string,也可以接受 values?: Record<string, string | number>。消息目录中存储的是句子模板;译文可以将 {name} 移到符合目标语言语法的位置。

说明有歧义的消息所表达的含义 #

“保存”既可以指提交表单,也可以指收藏文章。即使英文源文本完全相同,上下文也能将两者区分为不同的消息:

ts
import { computeKey } from "@lingo.dev/react";

const submitKey = computeKey("Save", "Submit changes to account settings");
const bookmarkKey = computeKey("Save", "Bookmark this article for later reading");

这两条消息的键不同,翻译者可以为各自的操作选择合适的动词。“向用户显示的文本”这类上下文无法消除歧义;请描述可能影响措辞的操作、受众或限制条件。

提取器会将这些信息写入消息目录的 @context 注释中,用于指导翻译,而不会显示在界面上。请将通用的术语、指令和品牌语调要求放在本地化引擎的翻译上下文中,并在调用处保留每条消息特有的含义说明。

消息标识 #

computeKey(source: string, context?: string): string 根据源文本和上下文生成一个八字符的键。它先用空字符分隔符将非空上下文与源文本连接起来,再将组合后的输入规范化为 Unicode NFC 格式,最后对其 UTF-8 字节进行哈希计算。

规范等价的 Unicode 表示形式共用同一个键。修改措辞、标点、大小写、空白字符或上下文,都可能生成新的键。值不参与哈希计算,因此,无论问候语中的姓名是什么,都会使用同一个消息条目。

修改源文本或上下文后,请重新提取,并检查新增条目和孤立条目。如果不核对含义就将译文复制到新键下,可能会保留原本希望通过修改源文本来替换的措辞。哈希值的数量有限;提取器会检测所收集消息之间的哈希碰撞。

确保调用可被提取 #

在 l.text(...) 等调用中,请使用字面量形式的源字符串和上下文。运行时可以接收计算得到的字符串,但提取器无法推断程序可能构造出的所有字符串。调用接收者应为 l,或通过 useLingo 或 createLingo 创建的受支持变量。提取参考介绍了可识别的形式。

请用占位符传入动态数据,而不是生成 "Welcome, " + name 这样的源字符串。稳定的模板可供提取,每种含义只需翻译一次,就能重复用于不同的值。

插值与 ICU #

简单占位符使用 {name} 这样的名称。传入的值会转换为文本。未提供值的简单占位符会保留在文本中;如果省略 values 对象,则会直接返回选定的模板,不进行插值。

对于随数量或类别变化的语法,文本格式化器通过 intl-messageformat 支持复杂的 ICU 模式:

ts
import { createLingo } from "@lingo.dev/react";

const l = createLingo("en");
const label = l.text("{count, plural, =0 {No files} one {# file} other {# files}}", {
  context: "Number of files attached to a message",
  values: { count: 0 },
});

这会返回 No files。显式的 =0 分支将零与该语言区域的常规复数类别区分开来。请提供选定模板所需的所有参数。如果复杂 ICU 的解析或格式化失败,运行时会返回该模板,并报告去重后的开发错误;它不会用重新格式化的源文本替换格式有误的译文。

复数与选择提供辅助函数,用于处理完整的备选文本。富文本通过独立的命名标签解析器插入 React 元素。请使用适当的形式,不要将复杂的 ICU 表达式混入富文本模板。