提供器与钩子
提供语言区域和消息目录,合并共享消息与页面消息,切换语言时避免混用渲染输入。
LingoProvider 为组件子树提供一组语言区域和消息目录。useLingo() 读取最近的提供器,并返回与这组输入对应的消息和格式化方法。
这些渲染示例需要 React 19。使用提供器前,请先按照 React 快速入门安装指南完成安装。
import { LingoProvider, useLingo, type Messages } from "@lingo.dev/react";
function SaveButton() {
const l = useLingo();
return (
<button type="submit">
{l.text("Save", { context: "Submit changes to account settings" })}
</button>
);
}
export function Settings({ messages }: { messages: Messages }) {
return (
<LingoProvider locale="fr" messages={messages}>
<SaveButton />
</LingoProvider>
);
}渲染 Settings 前,请先加载法语消息。提供器接受的是 Messages,即一个 Record<string, string>,而不是文件路径、Promise 或解析后的 JSONC 条目列表。消息目录加载会生成这一映射。
提供器输入 #
| 属性 | 约定 |
|---|---|
locale | 必填字符串,用于消息查找诊断、语法处理和格式化。 |
messages | 可选的字符串映射,以哈希值为键;默认为 {}。 |
children | 必填的 ReactNode 子树。 |
即使消息目录为空,子树仍可按语言区域进行格式化;消息调用则使用各自的源模板。提供器本身不会设置文档的语言或方向。
请在提供器内的后代组件中调用 useLingo,在提供器外调用会抛出异常。在同一个组件中返回提供器,并不会让该组件的钩子处于提供器内部,因此请将提供器包装组件与读取钩子的组件分开。
合并共享消息与页面消息 #
嵌套提供器使用相同的语言区域字符串时,它们的映射会合并。子级条目会覆盖父级中键相同的条目,其余父级条目仍然可用。因此,路由可以添加页面消息,而无需重复提供共享的导航消息。
<LingoProvider locale="fr" messages={sharedMessages}>
<LingoProvider locale="fr" messages={pageMessages}>
<SettingsPage />
</LingoProvider>
</LingoProvider>这里的 sharedMessages 和 pageMessages 都是已加载的法语映射。如果内层的语言区域改为 es,内层提供器就会独立运作:缺失的西班牙语消息会回退到源文本,而不会借用法语文本。比较依据是语言区域字符串的字面值,因此请在整个应用中保持语言区域的拼写一致。
同时切换语言区域与消息目录 #
将渲染输入成对存储,例如 { locale: "fr", messages: frenchMessages }。先加载下一个映射,再通过一次状态更新替换这对值。如果只更改语言区域,可能会出现文本仍为法语、数字却采用西班牙语格式的情况。
加载下一个消息目录时,请根据应用的交互设计,继续显示上一对输入对应的内容,或显示加载状态。在使用路由的应用中,请采用相应的 Next Pages 或 TanStack 实践方案;它们的切换器加载新输入的方式不同。
不使用钩子创建 Lingo 对象 #
当函数需要在 React 组件之外获取字符串时,请使用 createLingo(locale: string, messages?: Messages): Lingo:
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en-US");
const title = l.text("Account settings", { context: "Settings page title" });
const percentage = l.percent(0.125, { maximumFractionDigits: 1 });这会返回 Account settings,并按该语言区域将比率格式化为 12.5%。它不会发起翻译请求,也不会订阅提供器。语言区域或消息发生变化时,请创建新对象。
createLingo 和 useLingo 都提供 locale、direction、script 和 region。使用语言区域元数据设置文档属性,并在水合期间保持输入一致。