React 消息

将源文本和上下文保留在组件中,再用译文目录渲染消息,支持变量值、语法规则和 React 元素。

组件中的消息应与它所说明的操作放在一起。表单上的“保存”用于提交更改;文章上的“保存”则用于添加书签。将源文本与其含义放在一起,既能让译者分清两者,也能让开发者直接理解组件,无需到另一个文件中查找键。

@lingo.dev/react 使用显式消息调用:

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

export function SaveButton() {
  const l = useLingo();
  return <button type="submit">{l.text("Save", { context: "Submit changes to account settings" })}</button>;
}

源文本和上下文共同标识目录中的一条消息。目录是键与译文字符串之间的映射。提供器提供该目录和当前语言区域。组件会收到译文;如果对应条目缺失或为空,则回退到源文本。

让组件用另一种语言呈现 #

首先,渲染本地译文。一个小型目录就能直观展示查找过程,无需账户,也无需发起网络请求。

在应用工作流中,lingo extract 将可识别的调用收集到源 JSONC 目录中,并生成 TypeScript 声明。CLI 将该文件提交翻译,再取回目标文件。应用的加载器将文件转换为提供器所需的字符串映射。目录提取与加载完整介绍了这一流程,也说明了如何在译后的 JSONC 丢失元数据注释时,保留仍在使用的消息。

渲染在本地完成。运行时不会连接本地化引擎,也不会携带 API 密钥。服务端翻译应放在 API 集成中处理,再通过应用常规的构建或请求加载流程,将生成的目录传入应用。

写出读者需要的消息 #

使用带占位符的完整句子,不要拼接分别翻译的片段。在其他语言中,姓名、数量或链接可能需要出现在句子的不同位置。

消息需求使用方式
带变量值的纯文本l.text。
链接、强调或其他 React 元素l.rich,配合具名渲染回调使用。
随数量变化的语法或按类别选择l.plural 和 l.select。
数字、日期、列表或适配语言区域的文本操作格式化方法,使用原生 Intl。

提供器与钩子参考文档介绍了嵌套目录,以及供组件外部代码使用的 createLingo。语言区域元数据提供书写方向、文字系统和地区信息,帮助你有依据地选择文档结构和布局。

围绕消息完成应用集成 #

Next.js Pages 和 TanStack Start 适配器将目录接入各自的路由系统。如果采用其他架构,请在渲染前加载语言区域和消息,并在服务端渲染与水合期间保持这组数据不变。

使用生成的类型,在编辑时发现源文本、上下文和变量值中的错误。通过渲染测试检查实际加载的模板。如果译文没有显示,故障排查会带你追踪从组件到目录的查找过程。

导出项 #

根入口导出 LingoProvider、useLingo、createLingo 和 computeKey,以及类型 LingoProviderProps、Lingo、Messages、LingoMessages、MessageKey、TextOptions、RichOptions、PluralForms、SelectForms 和 FormatMethods。独立的 @lingo.dev/react/testing 入口导出 withLingo 和 renderStatic。