Vite + React

アルファ

Lingo.dev Compiler はアルファ版です。動作は安定しておらず、本番環境での利用は推奨されません。また、API はリリースごとに変更される可能性があります。

Lingo.dev Compiler は、lingoCompilerPlugin を通じて Vite と統合されます。これは、ビルド時に React コンポーネントを変換して翻訳を埋め込む Vite プラグインです。Hot Module Replacement にも完全対応しているため、開発中の翻訳変更も即座に反映されます。

前提条件#

要件

React を使用する Vite 5 以降
Node.js 18 以降
@lingo.dev/compiler がインストール済みであること

インストール#

bash

pnpm install @lingo.dev/compiler

vite.config.ts を設定する#

Vite の設定に lingoCompilerPlugin を追加します。このプラグインは、必ず react() プラグインの前に配置してください。React プラグインが処理する前に Compiler が 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 を処理してしまい、Compiler が翻訳可能なテキストを検出できなくなります。plugins 配列では、Lingo プラグインを必ず先頭に配置してください。

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 はロケールコンテキストを初期化し、アクティブなロケールに対応する翻訳辞書を読み込みます。

Hot Module Replacement#

このプラグインは Vite の HMR システムと統合されています。コンポーネント内の翻訳対象テキストを編集すると、

ソーステキストを編集

JSX 内のテキストを変更します。たとえば、見出しを "Welcome" から "Welcome back" に更新します。

Compiler が変更を検出

プラグインが HMR の更新を検知し、変更された文字列を特定して、新しい翻訳を生成します（開発モードでは疑似翻訳）。

ブラウザに即座に反映

ページ全体を再読み込みすることなく、翻訳済みコンポーネントが再レンダリングされます。.lingo/metadata.json 内の翻訳メタデータもディスク上で更新されます。

sourceRoot の設定#

sourceRoot オプションでは、Compiler が翻訳可能なテキストをスキャンする対象ファイルを指定します。標準的な Vite + React プロジェクトでは、

{
  sourceRoot: "src",
}

プロジェクト構成	推奨される sourceRoot
標準 (`src/`)	`"src"`
共有パッケージを含むモノレポ	`"."`（プロジェクトルート）
カスタムディレクトリ	コンポーネントディレクトリへのパス

大規模なコードベースでは、sourceRoot を絞り込むことでビルド時間を短縮できます。特定のファイルだけを翻訳対象にしたい場合は、useDirective: true を有効にし、それらのファイルに 'use i18n' を追加してください。詳しくは Project Structure を参照してください。

プロジェクト構成の例#

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

次のステップ#