useLingo

useLingo() 是组件接入运行时的入口。它会读取最近的 <LingoProvider>，并返回当前生效的 Lingo 对象——每个组件调用一次，保存这个引用，然后按需调用对应方法即可。

tsx

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

function Greeting() {
  const l = useLingo();
  return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}

如果在 provider 之外调用，它会直接抛错，所以测试环境也需要包裹 render——即使你并不关心测试里的翻译，也可以用 messages: {}。

`l.text(source, options)`——纯字符串#

最常用的调用方式。它会返回翻译后的字符串；如果当前 locale 没有对应翻译，就回退为源字符串。

tsx

l.text("Save", { context: "Form button" });
// → "Speichern" (de) / "Save" (en, fallback)

插值#

{placeholder} 片段会用 options.values 中的值进行替换。

tsx

l.text("Welcome back, {name}!", {
  values: { name: user.firstName },
  context: "Dashboard greeting",
});

缺失的值会原样渲染成 {name}——开发时很方便排查 bug，但测试里务必断言最终渲染结果，避免空值悄悄溜过去。

当源字符串包含 ICU 语法时#

如果源字符串里带有 plural / select / number / date 标记，运行时会自动升级处理——不需要额外 API。想用更友好的封装，可参见复数与 select。

`l.rich(source, options)`——React 子树#

当翻译文本里包含 React 组件（链接、粗体、<Icon/> 等）时，请使用 l.rich。翻译字符串中会带有类似 <link>...</link> 的占位标签；你只需要把每个标签映射到对应的渲染器。

tsx

l.rich("Click <link>here</link> for {topic}", {
  tags: {
    link: (children) => <a href="/help">{children}</a>,
  },
  values: { topic: "details" },
  context: "Footer help link",
});
// → <>Click <a href="/help">here</a> for details</>

自闭合标签也支持：

tsx

l.rich("Loading <spinner/>...", {
  tags: { spinner: () => <Spinner /> },
  context: "Inline loading state",
});

没有对应渲染器的标签会回退为原始文本——这样在开发时就能直观看到缺失标签的问题，而不是被悄悄吞掉。

不要把标记直接写进翻译字符串里。l.rich 的意义就在于让译者看到中性的占位符（<link>），而不是必须逐字保留、还很容易写坏的 <a href="...">。渲染器应定义在代码里，而不是 locale 文件中。

`l` 上的 locale 元数据#

除了翻译，这个对象还提供：

属性	类型	说明
`l.locale`	`string`	你传给 `LingoProvider` 的值。BCP-47。
`l.direction`	`"ltr"` \| `"rtl"`	通过 `Intl.Locale.textInfo` 和 RTL 回退语言列表计算得出。
`l.script`	`string` \| `undefined`	可推断时会自动推断（`"Latn"`、`"Cyrl"`、`"Arab"` 等）。
`l.region`	`string` \| `undefined`	根据 BCP-47 推断（`"US"`、`"DE"`、`"SA"` 等）。

这对布局决策很有帮助：

tsx

const l = useLingo();
return <div dir={l.direction}>...</div>;

格式化方法#

l 还提供 num、currency、percent、date、time、datetime、relative、list、displayName、sort、segment、fileSize、compact、unit——完整说明请参见格式化。它们都是对原生 Intl.* 格式化器的轻量封装，并以 l.locale 为基准。

在 React 之外#

useLingo 只能在组件内部使用。对于工具函数、路由 loader 或服务端代码，请直接构建同样的对象：

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

const l = createLingo("es", messages);
l.text("Hello", { context: "Email subject" });

它和 Lingo 的结构完全一致，不需要 provider。LingoProvider 本身底层用的也是 createLingo。

tsx

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

function Greeting() {
  const l = useLingo();
  return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}