渲染你的第一条翻译消息

使用本地消息目录显示西班牙语问候语、替换姓名,并验证源文本回退机制。

将一条英语源消息渲染为 Hola, Ana. 本示例自带西班牙语翻译,让你直观了解组件、消息目录和提供器如何协同工作。无需 Lingo.dev 账户或 API 密钥。

在 React 19 应用中安装 #

sh
npm install @lingo.dev/react@1.17.1

请使用现有的 React 19 应用完成本教程。虽然该软件包将 React 18 和 19 声明为对等依赖,但其提供器使用了 React 19 的上下文提供器简写语法。能在 React 18 项目中安装该软件包,并不代表它能在其中正常渲染。

添加问候语和消息目录 #

将此组件放入 src/App.tsx,并通过应用现有的入口进行渲染:

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

const messages = {
  [computeKey("Hello, {name}.", "Greeting on the account dashboard")]:
    "Hola, {name}.",
};

function Greeting() {
  const l = useLingo();
  return (
    <h1>
      {l.text("Hello, {name}.", {
        context: "Greeting on the account dashboard",
        values: { name: "Ana" },
      })}
    </h1>
  );
}

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

运行应用的开发命令,然后打开页面。标题会显示 Hola, Ana. 运行时会根据源文本和上下文计算出相同的键,找到西班牙语模板,并将 {name} 替换为 Ana。

消息目录存储的是完整句子,因此翻译时可以调整语序。姓名是一个值,不属于键的一部分;换用其他姓名时,仍会使用同一条目录条目。请在 l.text 调用中保留源文本和上下文的字面量形式,以便提取器之后能识别它们。

检查缺少翻译时的表现 #

暂时向提供器传入 messages={{}}。此时标题会显示 Hello, Ana. 源文本会用作回退模板,值替换仍会执行。值为 "" 的条目也会使用源文本。

恢复 messages,然后仅将调用中的上下文改为 "Greeting on the profile page"。这会改变消息标识,使原有翻译不再匹配。恢复原来的上下文,即可重新显示 Hola, Ana. 这些检查能帮你区分两种情况:消息目录缺失,以及请求的消息与已翻译的消息不匹配。

用提取出的消息目录替换本地映射 #

此组件已可进行提取。消息目录的提取与加载介绍了如何生成 locales/en.jsonc、在 CLI 配置中选择它、获取西班牙语目标目录,并安全加载。这是接下来要完成的完整任务;上面的本地示例仍可用于渲染测试。

如果应用使用了路由,请继续阅读 Next.js Pages 或 TanStack Start。切换语言区域时,需要同时更新为新的语言区域及其消息,确保界面不会将一种语言的文本与另一种语言的格式混用。