LingoProvider

LingoProvider 是用于保存当前 locale 和消息映射的 React 上下文。在应用根部包一层即可——其内部的所有内容都能通过 useLingo() 翻译字符串或读取 locale 元数据。

基础用法#

tsx

import { LingoProvider } from "@lingo.dev/react";
import messages from "./locales/es.json";

<LingoProvider locale="es" messages={messages}>
  <App />
</LingoProvider>

Props#

Prop	类型	必填	说明
`locale`	`string`	是	BCP-47 标记，例如 `"en"`、`"es"`、`"ar-SA"`。决定所有格式化行为以及 RTL 检测。
`messages`	`Messages`	否	以哈希为键的翻译映射。默认为 `{}`（所有内容都会回退到源文案）。
`children`	`ReactNode`	是	你的应用。

Messages 本质上就是 Record<string, string>——也就是 CLI 写入 locales/<locale>.json 时使用的同一种结构。

嵌套 Provider#

Provider 支持嵌套。具体规则取决于嵌套 Provider 的 locale 与父级是相同还是不同。

相同 locale —— 合并消息#

tsx

<LingoProvider locale="es" messages={sharedMessages}>
  {/* Route-scoped messages override shared on collision; missing keys fall through to shared. */}
  <LingoProvider locale="es" messages={dashboardMessages}>
    <Dashboard />
  </LingoProvider>
</LingoProvider>

适合按路由拆分 bundle，同时在根部保留一套通用的“shell”翻译。

不同 locale —— 相互独立#

tsx

<LingoProvider locale="es" messages={esMessages}>
  <Header />
  <LingoProvider locale="ar-SA" messages={arMessages}>
    {/* This subtree is entirely Arabic; the parent's es messages are NOT visible. */}
    <ArabicEmbed />
  </LingoProvider>
</LingoProvider>

当整个应用使用另一种语言时，如果你想让某个组件固定用指定语言渲染（比如引文、嵌入内容或预览面板），这会很方便。

运行时切换 locale#

把 locale 当作 React state 来管理——一旦它发生变化，下方所有使用 useLingo() 的组件都会用新的 locale 和消息对象重新渲染。

tsx

function AppRoot() {
  const [locale, setLocale] = useState("en");
  const [messages, setMessages] = useState({});

  async function switchTo(next: string) {
    const next_messages = await import(`./locales/${next}.json`);
    setLocale(next);
    setMessages(next_messages.default);
  }

  return (
    <LingoProvider locale={locale} messages={messages}>
      <LocaleSwitcher current={locale} onSelect={switchTo} />
      <App />
    </LingoProvider>
  );
}

在 Next.js 中，优先使用 @lingo.dev/react-next 提供的 useLocaleSwitch()——它能处理与路由联动的 locale 切换以及持久化。

可从上下文中读取的内容#

useLingo() 会返回当前激活的 Lingo 对象。除了 text() 和 rich()，它还包含：

locale —— 你传入的 BCP-47 字符串
direction —— "ltr" 或 "rtl"，通过 Intl.Locale.textInfo 计算得出，并带有已知 RTL 语言列表作为兜底
script —— 例如 "Latn"、"Cyrl"、"Arab"
region —— 例如 "US"、"DE"、"SA"

这些信息很适合用于条件化布局（例如在 RTL 中镜像图标）或分析打标——无需额外解析。

常见错误#

忘了包 <LingoProvider>。 useLingo() 在其外部调用时会直接抛错。错误信息会提示你添加一个 Provider；如果你是在测试里遇到它，请用带空 messages 的测试模式 Provider 包裹 render，以确保断言稳定。
直接传入异步加载的消息。 messages 必须是同步值。请先在父组件中 resolve promise（通过 Suspense 或 state），再把结果传下来。
切换 locale 时没有同步更新 messages。 Provider 会把这两个 prop 视为一组输入——请在同一次 useState 更新里一起修改，否则会短暂出现“新 locale + 旧翻译”的渲染状态。