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

简介

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

本指南将解释如何将 Lingo.dev Compiler 与 The Epic Stack 配合使用。The Epic Stack 是由 Kent C. Dodds 基于 Remix 构建的全栈 Web 应用框架。

您将学到什么

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

第 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: "app",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});

为了与 The Epic Stack 兼容，请确保：

sourceRoot 设置为 "app"
rsc 设置为 false

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

将编译器配置与现有配置合并并导出：

export default defineConfig((config) => {
  const configWithSentry = {
    ...viteConfig,
    plugins: [
      ...viteConfig.plugins!.filter(Boolean),
      MODE === "production" && process.env.SENTRY_AUTH_TOKEN
        ? sentryReactRouter(sentryConfig, config)
        : null,
    ].filter(Boolean),
  };

  return withLingo(configWithSentry);
});

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

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

第 4 步：加载本地化内容

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

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

加载词典

在 app/root.tsx 文件中：

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

在 loader 函数中调用 loadDictionary 函数：

const lingoDictionary = await loadDictionary(request);

将词典作为加载器数据的一部分返回：

return data(
  {
    user,
    requestInfo: {
      hints: getHints(request),
      origin: getDomainUrl(request),
      path: new URL(request.url).pathname,
      userPrefs: {
        theme: getTheme(request),
      },
    },
    ENV: getEnv(),
    toast,
    honeyProps,
    lingoDictionary,
  },
  {
    headers: combineHeaders(
      { "Server-Timing": timings.toString() },
      toastHeaders,
    ),
  },
);

提供翻译

在 app/root.tsx 文件中：

从 lingo.dev/react/client 导入 LingoProvider 组件：
```
import { LingoProvider } from "lingo.dev/react/client";
```
此组件是一个 React 上下文提供器，用于将编译器创建的占位符替换为本地化内容。

在 Layout 组件中，从数据加载器获取数据：

const data = useLoaderData<typeof loader | null>();

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

<LingoProvider>{/* 现有的应用程序代码 */}</LingoProvider>

将加载的词典传递给组件：

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

第五步：设置语言环境切换器

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

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

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

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

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

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

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

第 6 步：运行应用程序

要验证 Lingo.dev 编译器 是否已正确设置：

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

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

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

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

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

进一步阅读

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

The Epic Stack 快速入门

简介