按语言区域格式化值
使用原生 Intl 格式化数字、日期、列表和文本,并提供显示所需的单位和时间信息。
翻译后的消息仍包含价格、日期、数量和列表等值。Lingo 对象会按当前语言区域格式化这些值,无需在消息目录中查找。请使用渲染周围消息的同一个对象,确保消息和值采用相同的语言区域。
数字和数量 #
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en-US");
const price = l.currency(29.99, "USD");
const completion = l.percent(0.125, { maximumFractionDigits: 1 });
const temperature = l.unit(32, "celsius", { unitDisplay: "long" });价格格式化只处理传入的美元金额,不进行货币换算。百分比输入应为比率,因此 0.125 会显示为 12.5%,而 12.5 则表示 1250%。同样,单位辅助方法只为传入的摄氏温度值添加单位标签,不进行单位换算。
| 方法 | 值之后的参数 |
|---|---|
num(value: number) | 可选的 Intl.NumberFormatOptions。 |
currency(value: number, currency: string) | 货币代码,后接可选的数字格式选项。 |
percent(value: number) | 可选的数字格式选项。 |
unit(value: number, unit: string) | 单位标识符,后接可选的数字格式选项。 |
compact(value: number) | 可选的数字格式选项。 |
fileSize(bytes: number) | 无选项。 |
所有方法均返回字符串。货币、百分比和单位方法会强制使用各自对应的样式;compact 则在应用其他选项后,强制使用紧凑记数法。
fileSize 会将数值除以 1024 的幂,并使用固定标签 B、KB、MB、GB、TB 和 PB。数字按语言区域格式化:字节不保留小数位,更大的单位最多保留一位小数。1024 会显示为 1 KB;零显示为 0 B。请传入非负整数形式的字节数。对于负数或非整数的字节数,没有实用的显示规则;GB 等标签也不会翻译为法语的 Go。
日期、时间和相对偏移量 #
const instant = new Date("2026-10-10T12:00:00Z");
const timestamp = l.datetime(instant, { timeZone: "UTC" });
const date = l.date(instant, {
year: "numeric",
month: "2-digit",
day: "2-digit",
timeZone: "UTC",
});
const age = l.relative(-3, "day", { numeric: "auto" });这些调用使用上一个示例中的 l。date、time 和 datetime 接受 Date | number,后接可选的 Intl.DateTimeFormatOptions。数字时间戳以毫秒为单位,而非 Unix 秒。默认格式分别为中等长度的日期、简短时间,以及两者的组合。
传入 year 或 hour 等单独字段时,默认样式将不再生效。显式指定的样式选项可以覆盖默认值,但样式与单独字段的组合若不兼容,可能导致原生 Intl 抛出异常。如果服务器和浏览器需要显示相同的日期,请设置时区。
relative(value, unit, options?) 接受一个带符号的数字、一个 Intl.RelativeTimeFormatUnit 和可选的 Intl.RelativeTimeFormatOptions,并格式化传入的偏移量。请在应用代码中计算与基准时刻的差值,并按需更新;该方法不会读取时钟,也不会调度更新。
列表和文本操作 #
| 方法 | 结果和行为 |
|---|---|
list(items: string[], options?: Intl.ListFormatOptions) | 将已选定的标签连接成字符串;默认使用表示“和”的连接方式。 |
displayName(code, type) | 本地化名称或 undefined;类型为 language、region、script 或 currency。原生回退机制可能返回代码本身。 |
sort(items: string[], options?: Intl.CollatorOptions) | 按语言区域排序规则排列的新数组;原数组保持不变。 |
segment(text, granularity?) | 字符串片段,默认使用 grapheme,也可使用 word/sentence。单词模式会包含空白字符片段。 |
displayName 会捕获原生错误并返回 undefined,其他方法则不会这样处理。请在语言区域代码和选项传入应用时进行验证。
适配所支持的运行时 #
这些辅助方法会调用原生 NumberFormat、DateTimeFormat、RelativeTimeFormat、ListFormat、DisplayNames、Collator 和 Segmenter。该包不会补齐缺失的原生 API,也不会提供每个运行时所需的全部语言区域数据。
请在所支持的服务器和浏览器中测试有代表性的值。标点和格式惯例可能因 ICU 数据而异。进行水合时,除了语言区域,还需确保时间戳、时区和相对时间基准保持一致。