Vite 集成

Lingo.dev 编译器直接集成到 Vite 中，为 React 应用提供构建时的本地化支持。

按照以下步骤为您的 Vite + React 应用添加多语言支持。

或者探索 Vite 示例项目，体验编译器的实际效果。

前置条件

  • Vite 4+
  • React 18+
  • Node.js 18 或更高版本

第 1 步：安装包

安装 lingo.dev 包：

npm install lingo.dev

第 2 步：配置 Vite

在 vite.config.ts 中导入并配置编译器：

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import lingoCompiler from "lingo.dev/compiler";

const viteConfig = {
  plugins: [react()],
  // 您现有的 Vite 配置
};

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    targetLocales: ["es", "fr", "de"],
    models: {
      "*:*": "groq:mistral-saba-24b",
    },
  })(viteConfig),
);

第 3 步：设置身份验证

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

选项 1：Lingo.dev 引擎

Lingo.dev 编译器可以使用 Lingo.dev 引擎作为您的 AI 翻译引擎。它提供动态模型选择、自动路由、翻译记忆和术语表支持。提供免费和付费选项。

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

npx lingo.dev@latest login

如果您在浏览器流程中遇到问题，可以手动将 LINGODOTDEV_API_KEY 添加到 .env 文件中：


# .env

LINGODOTDEV_API_KEY=...

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

选项 2：替代 LLM 提供商

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

将您的 API 密钥添加到 .env 文件中：


# .env

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

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

第 4 步：添加提供商

在主入口文件（src/main.tsx）中导入提供商：

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.tsx";
import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";

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

第 5 步：可选：添加语言切换器

在您的 App 或 Header 中创建一个语言切换器组件：

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

function App() {
  return (
    <div className="App">
      <header>
        <LocaleSwitcher locales={["en", "es", "fr", "de"]} />
      </header>
      <main>
        <h1>欢迎使用我们的应用</h1>
        <p>此内容是自动翻译的</p>
      </main>
    </div>
  );
}

export default App;

第 6 步：构建和测试

启动开发服务器：

npm run dev

编译器将自动：

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

访问 http://localhost:5173 查看您的多语言应用。

配置选项

您可以自定义编译器行为：

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    sourceLocale: "en",
    targetLocales: ["es", "fr", "de", "ja"],
    lingoDir: "lingo",
    debug: false,
  })(viteConfig),
);

开发功能

热模块替换

编译器支持 Vite 的 HMR 功能以更新翻译：

// src/components/Welcome.tsx
export function Welcome() {
  return (
    <div>
      <h1>欢迎使用我们的应用</h1>
      <p>编辑此文本并查看翻译自动更新</p>
    </div>
  );
}

构建优化

Vite 的构建优化与编译器无缝协作：

  • 代码分割 包括翻译包
  • 资源优化 高效处理翻译文件
  • 树摇优化 移除未使用的翻译内容

示例项目结构

my-vite-app/
├── src/
│   ├── components/
│   │   └── Welcome.tsx
│   ├── App.tsx
│   ├── main.tsx
│   └── lingo/           # 生成的翻译文件
│       ├── meta.json
│       └── dictionary.js
├── vite.config.ts
├── package.json
└── .env

生产环境部署

  1. 构建您的应用程序：

    npm run build

  2. 提交翻译文件：

    git add src/lingo/
git commit -m "添加翻译"

  3. 部署 使用您首选的平台（Vercel、Netlify 等）

您的 Vite 应用将根据用户偏好自动提供本地化内容。

故障排除

常见问题

翻译未生成：确保您的 .env 文件中正确设置了 GROQ_API_KEY。

构建错误：确保 lingo/ 目录已包含在版本控制中。

HMR 不工作：在添加新的可翻译内容后，重启开发服务器。

下一步