快速开始

Lingo.dev Compiler 旨在在构建时使任何 React 应用程序支持多语言，而无需更改现有的 React 组件。

本快速入门指南将帮助您在不到 5 分钟的时间内为您的 React 应用程序添加多语言支持。

完成本指南后，您将能够：

  1. 在您的 React 应用程序中安装并配置 Lingo.dev Compiler
  2. 设置自动化的翻译提取和注入
  3. 拥有一个带有优化翻译的多语言应用程序

让我们开始吧！

前提条件

Lingo.dev Compiler 兼容现代 React 框架。在开始之前，请确保您使用的是以下支持的设置之一：

  • Next.js（App Router）
  • React Router / Remix
  • Vite + React

或者探索我们的演示应用：Next.js、React Router 和 Vite。

第 1 步：安装软件包

在您的项目中安装 lingo.dev 软件包：

npm install lingo.dev

第 2 步：配置您的框架

选择您的框架并按照特定的设置步骤：

Next.js

更新您的 next.config.js：

import lingoCompiler from "lingo.dev/compiler";

export default lingoCompiler.next({
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  models: "lingo.dev", // 选项 1：Lingo.dev 引擎
  // models: {
  //   "*:*": "groq:qwen/qwen3-32b", // 选项 2：GROQ
  //   "*:*": "google:gemini-2.0-flash", // 选项 2：Google AI
  //   "*:*": "openrouter:mistralai/mistral-small-24b-instruct-2501", // 选项 2：OpenRouter
  //   "*:*": "ollama:mistral-small3.1", // 选项 2：Ollama
  //   "*:*": "mistral:mistral-small-latest", // Mistral
  // },
})(nextConfig);

React Router / Remix

更新您的 vite.config.ts：

import lingoCompiler from "lingo.dev/compiler";

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    targetLocales: ["es", "fr", "de"],
    models: "lingo.dev", // 选项 1：Lingo.dev 引擎
    // models: {
    //   "*:*": "groq:qwen/qwen3-32b", // 选项 2：GROQ
    //   "*:*": "google:gemini-2.0-flash", // 选项 2：Google AI
    //   "*:*": "openrouter:mistralai/mistral-small-24b-instruct-2501", // 选项 2：OpenRouter
    //   "*:*": "ollama:mistral-small3.1", // 选项 2：Ollama
    // },
  })(viteConfig),
);

Vite

更新您的 vite.config.ts：

import lingoCompiler from "lingo.dev/compiler";

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    targetLocales: ["es", "fr", "de"],
    models: "lingo.dev", // 选项 1：Lingo.dev 引擎
    // models: {
    //   "*:*": "groq:qwen/qwen3-32b", // 选项 2：GROQ
    //   "*:*": "google:gemini-2.0-flash", // 选项 2：Google AI
    //   "*:*": "openrouter:mistralai/mistral-small-24b-instruct-2501", // 选项 2：OpenRouter
    //   "*:*": "ollama:mistral-small3.1", // 选项 2：Ollama
    //   "*:*": "mistral:mistral-small-latest", // Mistral
    // },
  })(viteConfig),
);

第 3 步：设置身份验证

Lingo.dev 编译器 会将您的内容发送到 AI 翻译引擎进行本地化，因此我们需要先进行身份验证。

选项 1. Lingo.dev 引擎

Lingo.dev 编译器 可以使用 Lingo.dev 引擎 作为您的 AI 翻译引擎。

它提供动态模型选择、针对每种语言对的自动模型路由、自动模型回退、考虑过往翻译的翻译记忆，以及支持项目领域特定术语的术语表功能。提供免费和付费选项，免费 Hobby 计划对大多数项目来说已经足够。

要进行身份验证，请运行：

npx lingo.dev@latest login

重要细节。 如果您使用的是 Brave 浏览器，或者您的浏览器扩展阻止了身份验证流程，您可以通过在 .env 文件中添加 LINGODOTDEV_API_KEY 环境变量手动进行身份验证：

LINGODOTDEV_API_KEY=...

您可以在 Lingo.dev 引擎 项目设置中找到该令牌。

选项 2. 替代 LLM 提供商

或者，您可以使用支持的 LLM 提供商之一的模型：

将您的 LLM 提供商的 API 密钥添加到环境中：


# .env

GROQ_API_KEY=gsk_...
GOOGLE_API_KEY=...
OPENROUTER_API_KEY=...
MISTRAL_API_KEY=...

注意： 在 Compiler 中使用之前，请确保激活您的 LLM 提供商账户并接受其服务条款。

第 4 步：添加 Provider

使用 LingoProvider 包裹您的应用以启用翻译：

Next.js

在您的 layout.tsx 文件中：

import { LingoProvider, loadDictionary } from "lingo.dev/react/rsc";

export default function Layout({ children }) {
  return (
    <LingoProvider loadDictionary={(locale) => loadDictionary(locale)}>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

React Router / Remix

在您的 root.tsx 文件中：

import { LingoProvider } from "lingo.dev/react/client";
import { loadDictionary } from "lingo.dev/react/react-router";

export async function loader(args) {
  return { lingoDictionary: await loadDictionary(args.request) };
}

export default function Root() {
  const { lingoDictionary } = useLoaderData();
  return (
    <LingoProvider dictionary={lingoDictionary}>
      <html>
        <body>
          <Outlet />
        </body>
      </html>
    </LingoProvider>
  );
}

Vite

在您的 main.tsx 文件中：

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

ReactDOM.createRoot(document.getElementById("root")).render(
  <LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
    <App />
  </LingoProviderWrapper>,
);

第 5 步：构建和测试

运行您的开发服务器：

npm run dev

编译器将自动：

  1. 扫描您的 React 组件以查找可翻译的文本
  2. 提取翻译键
  3. 使用 AI 生成翻译
  4. 在 lingo/ 目录中创建优化的翻译文件

您的应用现在是多语言的！编译器会创建版本化的字典，跟踪内容更改，并仅重新翻译已修改的内容。

可选：添加语言切换器

添加一个语言切换器，让用户可以更改语言：

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

export function Header() {
  return (
    <header>
      <LocaleSwitcher locales={["en", "es", "fr", "de"]} />
    </header>
  );
}

下一步