Vite + React

Alpha

Lingo.dev Compiler 目前仍处于 alpha 阶段。它尚不稳定，不建议用于生产环境，且 API 可能会在不同版本之间发生变化。

Lingo.dev Compiler 可通过 lingoCompilerPlugin 与 Vite 集成。这个 Vite 插件会在构建时转换 React 组件并注入翻译，同时完整支持热模块替换，因此你在开发过程中修改翻译内容后可立即看到更新。

前提条件#

要求

Vite 5+ 与 React
Node.js 18+
已安装 @lingo.dev/compiler

安装#

bash

pnpm install @lingo.dev/compiler

配置 vite.config.ts#

将 lingoCompilerPlugin 添加到 Vite 配置中。这个插件必须放在 react() 插件之前——顺序不能错，因为编译器需要在 React 插件处理 JSX 之前先完成转换。

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

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

插件顺序至关重要

如果把 lingoCompilerPlugin 放在 react() 之后，React 插件会先处理 JSX，导致编译器无法识别可翻译文本。请始终将 Lingo 插件放在 plugins 数组的第一位。

添加 LingoProvider#

在入口文件中，使用 LingoProvider 包裹应用的根组件：

tsx

// 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>
);

LingoProvider 会初始化 locale 上下文，并为当前激活的 locale 加载对应的翻译词典。

热模块替换#

该插件已接入 Vite 的 HMR 系统。当你编辑组件中的可翻译文本时：

编辑源文本

修改 JSX 中的任意文本——例如，将标题从 "Welcome" 改为 "Welcome back"。

编译器检测变更

插件会拦截 HMR 更新，识别发生变化的字符串，并生成新的翻译（或在开发模式下生成伪翻译）。

浏览器即时更新

翻译后的组件会重新渲染，无需整页刷新。.lingo/metadata.json 中的翻译元数据也会同步更新到磁盘。

sourceRoot 配置#

sourceRoot 选项决定了编译器会扫描哪些文件来查找可翻译文本。对于标准的 Vite + React 项目：

{
  sourceRoot: "src",
}

项目结构	推荐的 sourceRoot
标准（`src/`）	`"src"`
带共享包的 Monorepo	`"."`（项目根目录）
自定义目录	组件目录的路径

对于大型代码库，缩小 sourceRoot 的范围可以减少构建时间。如果你只需要为特定文件提供翻译，请启用 useDirective: true，并在这些文件中添加 'use i18n'。详见项目结构。

项目结构示例#

text

my-vite-app/
  src/
    main.tsx          # LingoProvider wraps <App />
    App.tsx           # Translatable components
    components/
      Header.tsx      # Automatically scanned
      Footer.tsx      # Automatically scanned
  .lingo/
    metadata.json     # Translation cache (commit this)
  vite.config.ts      # lingoCompilerPlugin configured here

下一步#