快速上手

npm install @lingo.dev/react

如果你使用 Next.js，还需要安装 @lingo.dev/react-next——它基于同一套运行时，额外提供了可感知路由的辅助能力。

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

export function App() {
  return (
    <LingoProvider locale="es" messages={esMessages}>
      <Page />
    </LingoProvider>
  );
}

messages 是一个以内容哈希为键的对象——CLI 输出到 locales/<locale>.json 的正是这种格式。首次运行时它会是空的，没关系：未翻译的字符串会回退到源文本。

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

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

l.text(source, { context }) 是标准调用方式。context 是必需的——它能帮助翻译者区分那些英文写法相同、但在其他语言里含义不同的字符串（比如动词“Save”和名词“Save”）。

lingo extract

这一步会扫描你的源代码，为 "Hello" 结合上下文计算出稳定哈希，并将其写入源语言文件（默认是 locales/en.jsonc）。每次修改后重新运行即可——提取是幂等的。

lingo push --backfill-missing

CLI 会上传源文件，请求引擎将其翻译成你配置的目标语言环境，再把结果下载回 locales/<locale>.json。从此以后，每次推送只会发送变更内容。

导入应用当前渲染语言环境对应的 JSON 文件（或根据用户动态选择），并将其传给 LingoProvider。第 3 步里的 hook 调用保持不变——现在 l.text("Hello", ...) 会返回翻译后的值，因为哈希已经和下载内容一一对应。