Vite 集成

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

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

或者探索 Vite 示例项目，亲自体验 Compiler 的功能。

前置条件

  • 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";
import lingoCompiler from "lingo.dev/compiler";

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

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    targetLocales: ["es", "fr", "de"],
  })(viteConfig),
);

第 3 步：设置身份验证

在 groq.com 创建一个免费账户并添加您的 API 密钥：


# .env

GROQ_API_KEY=gsk_...

第 4 步：添加 Provider

在主入口文件 (src/main.tsx) 中导入 provider：

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 不工作：在添加新的可翻译内容后，重启开发服务器。

下一步