Vite 快速入门

简介

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

本指南将解释如何使用 Vite 设置 Lingo.dev Compiler。

您将学习到的内容

• 如何在 Vite 项目中初始化 Lingo.dev Compiler
• 如何为您的 Vite 应用配置编译器
• 如何设置语言切换器以在不同语言环境之间切换

第 1 步：设置 API 密钥

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

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

设置 API 密钥的步骤：

1. 登录 Lingo.dev Engine。

2. 导航到 Projects 页面。

3. 点击 API key > Copy。

4. 将 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 文件进行以下更改：

1. 导入编译器：

   import lingoCompiler from "lingo.dev/compiler";

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

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

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

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

   export default withLingo(viteConfig);

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

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

第 4 步：加载本地化内容

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

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

在 src/main.tsx 文件中：

1. 从 lingo.dev/react/client 导入 LingoProviderWrapper 组件和 loadDictionary 函数：

   import {
     LingoProviderWrapper,
     loadDictionary,
   } from "lingo.dev/react/client";

   LingoProviderWrapper 组件是一个上下文提供器，用于将编译器创建的占位符替换为本地化内容。

   loadDictionary 函数：

   • 从 lingo-locale cookie 中获取当前语言环境
   • 当未定义语言环境时，回退到 "en"
   • 从 dictionary.js 文件中加载本地化内容

2. 将 App 组件包裹在 LingoProviderWrapper 组件中，并将 loadDictionary 函数传递给它：

   <LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
     <App />
   </LingoProviderWrapper>

第 5 步：设置语言切换器

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

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

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

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

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

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

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

第 6 步：运行应用程序

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

1. 启动开发服务器：

   npm run dev

2. 访问 localhost:5173。

3. 使用 LocaleSwitcher 组件在不同语言环境之间切换。

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

替代方案：手动设置 Cookie

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

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

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

延伸阅读

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