处理复数、日期和数字
由语言区域决定语法和格式,由应用程序掌控数值、单位和时区。
表达项目数量时,需要明确两件事:应用程序要表达的数值,以及读者的语言如何表达这一数量。日期和金额也需要做同样的区分。在渲染之前,始终将值保留为结构化数据,以便在渲染时明确选择语法、分隔符、货币和时区。
这些示例使用 @lingo.dev/react。原生资源系统有各自的消息语法和生成器;使用类似 ICU 的表示法,并不意味着所有运行时都可以互换。
为格式化器提供完整消息 #
在 LingoProvider 下的组件中,将数值形式的计数传入复数消息:
const l = useLingo();
const label = l.plural(
count,
{ one: "# item", other: "# items" },
{ context: "Number of items in the shopping cart" },
);从 @lingo.dev/react 导入 useLingo;count 是应用程序中的数值。运行时会构建 ICU 消息,并根据当前语言区域格式化消息目录中的译文。one 和 other 是语法类别。如果只是将翻译后的名词拼接在格式化后的数字后面,就无法选择相应的语法类别,也无法调整词序。
plural 辅助函数会构建具名的 CLDR 类别,但不包含 =0 这样的精确数值分支。若要为产品设置数量为零时的专用消息,请使用文本处理路径,并显式写出 ICU 表达式:
l.text("{count, plural, =0 {No items} one {# item} other {# items}}", {
context: "Cart count with a distinct empty state",
values: { count },
});目标语言可能需要比英语更多的类别。请检查译文,并测试其语言区域会选用的各种形式,不要强行让所有语言沿用源文的分支。复数与选择分支介绍了支持的形式和提取行为。
若要根据语义选择不同表达,请使用稳定的选择器值:
l.select(role, {
admin: "Manage team settings",
member: "View team settings",
other: "View settings",
}, { context: "Settings action for the user's team role" });应用程序提供 role。翻译各分支的消息时,保留 admin、member 和必需的 other 回退分支。未知值会使用 other。
区分表示位置的序数与表示数量的基数 #
序数用于描述位置。对于以下这类消息,请使用文本处理路径中的复杂 ICU 格式化器:
l.text("You finished {position, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}", {
context: "Participant's finishing position in a competition",
values: { position },
});这些后缀是英语源文的用法,并非通用规则。目标译文必须用目标语言自身的方式表达位置。提供 values 即可启用文本处理路径中的格式化功能;生成的声明会检查调用约定,但不会验证每一个嵌套的 ICU 分支。
明确指定货币和百分比单位 #
使用数值金额及其对应的货币代码:
const price = l.currency(1234.5, "EUR");
const discount = l.percent(0.15);第一次调用会将金额格式化为欧元,并不会把其他货币换算成欧元。第二次调用表示百分之十五,因为输入值是一个小数比例。若传入 15,表达的数量就会不同。将这些格式化后的字符串插入句子时,请通过具名的 values 传入,不要拼出新的源字符串。
格式化辅助函数还支持数字、单位、列表及其他基于 Intl 的值。请检查每个辅助函数的默认设置和支持的选项。根据语言区域进行格式化,并不意味着所有自定义单位标签都会被翻译;无效选项仍可能导致失败。
明确日期的含义和显示时区 #
时间戳表示一个具体时刻;日历日期则可以表示不带时区的某一天。不要将仅含日期的截止期限转换为午夜时刻,除非这种转换符合产品所要表达的含义。
对于具体时刻,请指定要使用的显示时区:
const instant = new Date("2026-01-02T00:30:00Z");
const date = l.date(instant, { timeZone: "UTC" });
const time = l.time(instant, { timeZone: "UTC" });这些辅助函数按当前语言区域呈现内容,并使用 UTC 作为显示时区。也可以直接使用底层的标准 API:
new Intl.NumberFormat("de-DE", {
style: "currency", currency: "EUR",
}).format(1234.5);
new Intl.DateTimeFormat("en-US", {
dateStyle: "medium", timeZone: "UTC",
}).format(new Date("2026-01-02T00:30:00Z"));让富文本消息遵循受支持的语法 #
l.rich 将具名标签映射到 React 组件,并对简单占位符进行插值。它不使用 l.text 的复杂 ICU 格式化器。当代码提供链接渲染器和地区值时,“阅读我们面向 {region} 的<link>配送政策</link>”这样的句子适合采用此处理路径。在其中加入复数或序数,并不会让它获得 ICU 支持。
将交互定义保留在代码中;当消息同时涉及富文本结构和语法需求时,请选择受支持的消息设计。未知标签会保留为字面文本,同名标签嵌套时的配对支持也有限。请参阅富文本交互消息。
检查含义会发生变化的情况 #
测试数量为 0、1、2 和较大数值的情况;如果产品允许小数,也要测试小数。对于英语序数,请涵盖 1、2、3、11、12、13 和 21;对于目标语言,请采用符合其语言区域的预期表达。还要测试未知选择器值、有实际意义的负数金额,以及临近午夜的同一时刻在两个时区中的显示。
进行这些检查时,请加载实际的目标语言消息目录。缺失或为空的译文可能会回退到源文,因此,仅凭看似合理的输出,无法确认目标语言的覆盖情况。将渲染后的值与预期的数量、日期和消息逐一比较,然后审核语言表达本身。