快速开始

在不到 5 分钟内为你的 React 应用添加多语言支持。

前置条件

  • Node.js 18 及以上
  • 使用 Next.js（App Router）或 Vite 的 React 应用

安装

pnpm install @lingo.dev/compiler

配置

Next.js

将你的配置改为 async，并用 withLingo 包裹：

// next.config.ts
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr"],
    models: "lingo.dev",
    dev: {
      usePseudotranslator: true, // Fake translations for development
    },
  });
}

Vite

在 Vite 配置中添加 Lingo 插件：

// vite.config.ts
import { defineConfig } from "vite";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "de", "fr"],
      models: "lingo.dev",
      dev: {
        usePseudotranslator: true,
      },
    }),
    // ...other plugins
  ],
});

设置 Provider

Next.js

在根布局中用 LingoProvider 包裹你的应用：

// app/layout.tsx
import { LingoProvider } from "@lingo.dev/compiler/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

Vite

在入口文件中用 LingoProvider 包裹你的应用：

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { LingoProvider } from "@lingo.dev/compiler/react";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <LingoProvider>
      <App />
    </LingoProvider>
  </StrictMode>
);

认证

编译器默认使用 Lingo.dev Engine 进行翻译。

选项 1：Lingo.dev Engine（推荐）

在 lingo.dev 注册并进行认证：

npx lingo.dev@latest login

Windows 用户： 如果 npx lingo.dev 在您的环境中无法运行：

  1. 安装该软件包：npm install lingo.dev@latest
  2. 请改用 npx lingo（例如，npx lingo login）

这会将你的 API 密钥保存在本地。免费 Hobby 套餐已足够满足大多数项目需求。

遇到认证问题？ 如果你的浏览器阻止了认证流程，请手动将 API 密钥添加到 .env：

LINGODOTDEV_API_KEY=your_key_here

在 Lingo.dev 项目设置中查找你的 API 密钥。

选项 2：直接使用 LLM 提供商

或者，直接使用任意受支持的 LLM 提供商。更新你的配置：

{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
    // or "google:gemini-2.0-flash"
    // or "openai:gpt-4o"
    // or "anthropic:claude-3-5-sonnet"
  }
}

将对应的 API 密钥添加到 .env：

GROQ_API_KEY=your_key
# or GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY

查看 翻译提供商 以获取所有受支持的提供商列表。

运行开发服务器

启动你的 dev 服务器：

npm run dev

编译器将会：

  1. 扫描你的 JSX 以查找可翻译文本
  2. 生成伪翻译（用于可视化哪些内容会被翻译）
  3. 注入到你的组件中
  4. 将元数据存储在 .lingo/metadata.json

为什么要用伪翻译？ 它们即时生成（无需 API 调用），能准确显示哪些内容会被翻译，并帮助你测试 UI 在不同文本长度下的表现——无需消耗 API 配额。

测试翻译

添加一个简单组件：

export function Welcome() {
  return (
    <div>
      <h1>Welcome to our app</h1>
      <p>This text will be translated automatically</p>
    </div>
  );
}

无需更改代码——文本会被自动提取并翻译。

添加语言切换器（可选）

让用户切换语言：

"use client"; // For Next.js

import { useLingoContext } from "@lingo.dev/compiler/react";

export function LanguageSwitcher() {
  const { locale, setLocale } = useLingoContext();

  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
      <option value="en">English</option>
      <option value="es">Español</option>
      <option value="de">Deutsch</option>
      <option value="fr">Français</option>
    </select>
  );
}

生成真实翻译

准备好生成真实翻译时，更新你的配置：

{
  dev: {
    usePseudotranslator: false, // Disable fake translations
  }
}

重启你的开发服务器。编译器现在会为所有新增或变更的文本生成真实的 AI 翻译。

**关注成本？**伪翻译免费且即时。只有在需要审核实际翻译质量时才建议关闭伪翻译。

常见问题

我需要标记每一个可翻译字符串吗？ 不需要。编译器会自动检测 JSX 文本。如果你想手动选择翻译内容，可以设置 useDirective: true，并在需要翻译的文件顶部添加 'use i18n'。

动态内容或 props 怎么办？ 编译器会自动处理 alt、aria-label 和 placeholder 等字符串属性。对于动态文本，请使用模板语法：<p>Hello {name}</p> 可正常工作。

可以自定义特定翻译吗？ 可以。请使用 data-lingo-override 属性：

<h1 data-lingo-override={{ es: "Bienvenido", de: "Willkommen" }}>
  Welcome
</h1>

如何提交翻译？ 将 .lingo/ 目录提交到版本控制。该目录包含元数据和缓存的翻译内容——可以安全提交，并应与代码一同进行版本管理。

后续步骤