クイックスタート

Reactアプリに5分以内で多言語対応を追加しましょう。

必要条件

  • Node.js 18以上
  • Next.js（App Router）またはViteを使用したReactアプリケーション

インストール

pnpm install @lingo.dev/compiler

設定

Next.js

設定ファイルを非同期にして、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
  ],
});

プロバイダーのセットアップ

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

APIキーはLingo.devのプロジェクト設定で確認できます。

オプション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

サポートしているすべてのプロバイダーは翻訳プロバイダーをご覧ください。

開発サーバーを起動する

開発サーバーを起動してください：

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/ディレクトリをバージョン管理にコミットしてください。ここにはメタデータとキャッシュされた翻訳が含まれており、コードと一緒にバージョニングできます。

次のステップ