Lingo.dev - Automated AI localization for web & mobile apps

简介

Lingo.dev Compiler 是一款由 AI 驱动的工具，可以在不更改现有组件的情况下实现基于 React 的应用程序的本地化。您只需配置一些内容，将您的应用程序包裹在一个上下文提供器中，就完成了——您的应用程序已实现本地化。

本指南将解释如何将 Lingo.dev Compiler 与 React Router 的 v6 版本配合使用，React Router 是一个用于 React 的客户端路由库。如果您使用的是 v7，请参阅 React Router 快速入门 (v7)。

您将学到什么

如何在 React Router 中初始化 Lingo.dev Compiler
如何配置编译器以兼容 React Router
如何设置语言切换器以在不同语言环境之间切换

第 1 步：设置 API 密钥

Lingo.dev Compiler 使用大型语言模型（LLM）通过 AI 实现应用程序的本地化。要使用这些模型之一，您需要从支持的提供商处获取 API 密钥。

为了尽快开始，我们推荐使用 Lingo.dev Engine——我们自己的托管平台，提供每月 10,000 个免费使用的令牌。

设置 API 密钥的步骤：

登录 Lingo.dev Engine。
导航到 Projects 页面。
点击 API key > Copy。

将 API 密钥存储在环境变量中：

export LINGODOTDEV_API_KEY="<your_api_key>"

替代方案：自定义 LLM 提供商

您不必使用 Lingo.dev Engine。您可以配置编译器与多个自定义 LLM 提供商集成，包括：

Groq
Google
Mistral
Ollama
OpenRouter

第 2 步：安装软件包

Lingo.dev Compiler 作为 lingo.dev npm 软件包的一部分分发。要安装它，请使用您喜欢的包管理器：

npm install lingo.dev

第 3 步：初始化编译器

Lingo.dev 编译器 集成了 Vite，并在构建时运行。要接入 Vite 的构建流程，请对 vite.config.ts 文件进行以下更改：

导入编译器：

import lingoCompiler from "lingo.dev/compiler";

使用 vite 方法初始化编译器：

const withLingo = lingoCompiler.vite({
  sourceRoot: "src",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});

为了与 React Router 兼容，请确保：

sourceRoot 设置为 "src"
rsc 设置为 false

要了解更多可用选项，请参阅编译器选项。

使用编译器包装现有的 Vite 配置：

const viteConfig: UserConfig = {
  plugins: [react()],
};

export default withLingo(viteConfig);

完成此配置后，Lingo.dev 编译器 将会：

遍历代码库的抽象语法树 (AST)
查找可本地化的内容（例如 JSX 元素中的文本和某些属性值）
使用配置的 AI 模型生成翻译
将原始内容和翻译内容存储在 dictionary.js 文件中
用占位符替换本地化内容

第 4 步：加载本地化内容

在编译器处理您的应用并生成翻译后，您需要加载并将这些本地化内容提供给用户。这包括：

根据用户的语言偏好加载相应的字典
通过上下文提供器将加载的翻译提供给您的应用

加载字典

在您的根路由文件中：

从 lingo.dev/react/react-router 导入 loadDictionary 函数：
```
import { loadDictionary } from "lingo.dev/react/react-router";
```
此函数：
- 从 lingo-locale cookie 中获取当前语言环境
- 当未定义语言环境时，回退到 "en"
- 从 dictionary.js 文件加载本地化内容

在 loader 函数中调用 loadDictionary 函数：

import { LoaderFunctionArgs } from "react-router-dom";

export async function loader({ request }: LoaderFunctionArgs) {
  const lingoDictionary = await loadDictionary(request);
  return {
    lingoDictionary,
  };
}

提供翻译

在您的根组件中：

从 lingo.dev/react/client 导入 LingoProvider 组件：
```
import { LingoProvider } from "lingo.dev/react/client";
```
此组件是一个 React 上下文提供器，用于将编译器创建的占位符替换为本地化内容。
在根组件中，从数据加载器获取数据：
```
const data = useLoaderData<typeof loader>();
```

使用 LingoProvider 组件包裹应用程序：

<LingoProvider dictionary={data?.lingoDictionary}>
  {/* 现有的应用程序代码 */}
</LingoProvider>

第 5 步：设置语言切换器

为了让用户能够在不同语言环境之间切换，从 lingo.dev 包中导入 LocaleSwitcher。这是一个未添加样式的组件，功能包括：

渲染可用语言环境的下拉菜单
允许用户选择语言环境
记住用户选择的语言环境以便下次访问

要使用该组件，可以将其嵌入到应用程序的任意位置，并将 locales 属性设置为包含配置的源语言和目标语言的数组：

import { LocaleSwitcher } from "lingo.dev/react/client";

<LocaleSwitcher locales={["en", "es"]} />;

替代方案：自定义语言切换器

您不必使用 LocaleSwitcher 组件。您可以实现自定义的语言切换逻辑和界面。唯一的要求是将活动语言环境读写到 lingo-locale cookie 中。

第 6 步：运行应用程序

要验证 Lingo.dev Compiler 是否已正确设置：

启动开发服务器：
```
npm run dev
```
访问 localhost:5173。
使用 LocaleSwitcher 组件在不同语言环境之间切换。

页面应重新加载并显示本地化内容。

如果您未使用 LocaleSwitcher 组件，另一种验证本地化是否正常工作的方法是手动设置 lingo-locale cookie。

如果您使用的是 Google Chrome，请按照以下步骤操作：

导航到 视图 > 开发者 > 开发者工具。
转到 应用程序 选项卡。
在左侧边栏的存储下，展开 Cookies 并选择站点的 URL。
在 cookies 表格中，右键单击任意位置并选择添加。
在名称列中，输入 lingo-locale。
在值列中，输入所需的语言区域（例如，es）。
按 Enter 键保存 cookie。
刷新页面以应用 cookie。

进一步阅读

要了解编译器的工作原理，请参阅工作原理。
要学习如何配置编译器，请参阅编译器选项。

React Router (v6) 快速入门

简介