移行ガイド - Lingo.dev Compiler

旧コンパイラ（lingo.dev/compiler）から新しい@lingo.dev/compilerへ移行します。

なぜ移行するのか？

新しいコンパイラは以下を提供します：

より良いDX — デフォルトで自動（'use i18n'は不要）
より良いパフォーマンス — より高速なビルド、より良いHMR
ビルドモード — 開発/CI/本番環境の関心事を分離
手動オーバーライド — data-lingo-override属性
カスタムロケールリゾルバー — 柔軟なロケール検出
開発ツール — 疑似翻訳、開発ウィジェット（近日公開）
よりクリーンなアーキテクチャ — より良い関心事の分離

破壊的変更

1. パッケージ名

旧：

npm install lingo.dev

新：

npm install @lingo.dev/compiler

2. インポートパス

旧：

import lingoCompiler from "lingo.dev/compiler";
import { LingoProvider } from "lingo.dev/react/rsc";

新：

import { withLingo } from "@lingo.dev/compiler/next";
import { LingoProvider } from "@lingo.dev/compiler/react";

3. 設定API

Next.js

旧：

// next.config.js
import lingoCompiler from "lingo.dev/compiler";

export default lingoCompiler.next({
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
})(nextConfig);

新：

// next.config.ts
import { withLingo } from "@lingo.dev/compiler/next";

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    sourceRoot: "./app", // New: specify source directory
    sourceLocale: "en",
    targetLocales: ["es", "de"],
    models: "lingo.dev",
  });
}

変更点：

設定は非同期関数である必要があります
新しいsourceRootオプション
lingoCompiler.nextの代わりにwithLingoラッパー

Vite

旧：

import lingoCompiler from "lingo.dev/compiler";

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

新:

import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en", // New: required
      targetLocales: ["es", "de"],
      models: "lingo.dev",
    }),
    react(),
  ],
});

変更点:

設定ラッパーではなくプラグインベースに変更
sourceLocaleが必須になりました
react()プラグインの前に配置してください

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

旧:

import { LingoProvider, loadDictionary } from "lingo.dev/react/rsc";

export default function Layout({ children }) {
  return (
    <LingoProvider loadDictionary={(locale) => loadDictionary(locale)}>
      {children}
    </LingoProvider>
  );
}

新:

import { LingoProvider } from "@lingo.dev/compiler/react";

export default function Layout({ children }) {
  return (
    <LingoProvider>
      {children}
    </LingoProvider>
  );
}

変更点:

loadDictionaryプロパティは不要になりました(内部で処理されます)
よりシンプルなAPIに変更

5. ファイル構造

旧:

lingo/
├── dictionary.js
├── meta.json
└── [locale]/
    └── *.json

新:

.lingo/
└── metadata.json

変更点:

ディレクトリ名が変更されました(.lingoからlingoへ)
複数のファイルではなく単一のメタデータファイルに変更
JSON構造が変更されました

6. "use i18n"ディレクティブ

旧: デフォルトで必須でした。翻訳したいすべてのファイルに追加する必要がありました:

'use i18n';

export function Component() { ... }

新: オプションになりました。デフォルトでは、すべてのファイルが自動的に翻訳されます。オプトインする場合:

{
  useDirective: true, // Enable opt-in behavior
}

その後、ディレクティブを追加してください:

'use i18n';

export function Component() { ... }

移行手順

ステップ1: パッケージの更新

# Uninstall old package
npm uninstall lingo.dev

# Install new package
npm install @lingo.dev/compiler

ステップ2: 設定を更新する

Next.js

変更前:

// next.config.js
import lingoCompiler from "lingo.dev/compiler";

export default lingoCompiler.next({
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
})(nextConfig);

変更後:

// 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"],
    models: "lingo.dev",
    dev: {
      usePseudotranslator: true, // Recommended for development
    },
  });
}

Vite

変更前:

import lingoCompiler from "lingo.dev/compiler";

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

変更後:

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"],
      models: "lingo.dev",
      dev: {
        usePseudotranslator: true,
      },
    }),
    react(),
  ],
});

ステップ3: プロバイダーを更新する

変更前:

import { LingoProvider, loadDictionary } from "lingo.dev/react/rsc";

export default function Layout({ children }) {
  return (
    <LingoProvider loadDictionary={(locale) => loadDictionary(locale)}>
      {children}
    </LingoProvider>
  );
}

変更後:

import { LingoProvider } from "@lingo.dev/compiler/react";

export default function Layout({ children }) {
  return (
    <LingoProvider>
      {children}
    </LingoProvider>
  );
}

ステップ4: 古いファイルをクリーンアップする

# Backup old translations (optional)
mv lingo lingo.backup

# Remove old directory
rm -rf lingo

# New directory will be created automatically
# on first build

ステップ5: 疑似翻訳機能でテストする

npm run dev

usePseudotranslator: trueを使用すると、即座に疑似翻訳が表示されます。以下を確認してください:

期待されるすべてのテキストが翻訳されている
コンパイルエラーがない
レイアウトがさまざまなテキスト長に対応している

ステップ6: 実際の翻訳を生成する

疑似翻訳機能を無効にするために設定を更新します:

{
  dev: {
    usePseudotranslator: false,
  }
}

開発サーバーを再起動します。コンパイラーは、新規または変更されたテキストに対して実際の翻訳を生成します。

ステップ7: 新しい翻訳をコミット

git add .lingo/
git commit -m "chore: migrate to @lingo.dev/compiler"
git push

機能マッピング

旧機能 → 新機能の対応

旧機能	新しい同等機能	備考
`dictionary.js`	`.lingo/metadata.json`	異なる形式
`meta.json`	`.lingo/metadata.json`	単一ファイルに統合
"use i18n"(必須)	"use i18n"(任意)	オプトイン方式に変更、必須ではない
カスタムプロンプト	`prompt`設定オプション	同じ機能
翻訳の編集	`data-lingo-override`	属性ベースのオーバーライド
翻訳のスキップ	`data-lingo-override` + 空	または`useDirective`を使用
翻訳のオーバーライド	`data-lingo-override`	属性ベース
ロケールの切り替え	`useLingoContext()`	`{ locale, setLocale }`を返す
LLMプロバイダー	`models`設定	同じプロバイダーをサポート

新機能(旧コンパイラにはない機能)

ビルドモード — translateとcache-only
疑似翻訳機能 — 即座に偽の翻訳を生成
開発ウィジェット — ブラウザ内編集(近日公開)
カスタムロケールリゾルバー — 柔軟なロケール検出
自動複数形対応 — ICU MessageFormatサポート
翻訳サーバー — 開発環境でのオンデマンド翻訳

既存の翻訳の移行

新しいコンパイラは異なるファイル形式を使用します。既存の翻訳は自動的に移行されません。

オプション:

オプション1: すべての翻訳を再生成

コンパイラに新しい翻訳を生成させる:

古いlingo/ディレクトリを削除
新しいコンパイラを実行
AIを使用して翻訳を生成

メリット: クリーンスタート、最新のAIモデルを使用 デメリット: APIコスト、ニュアンスが失われる可能性

オプション2: 手動移行スクリプト

旧形式を新形式に変換するスクリプトを作成します:

// migrate-translations.ts
import * as fs from "fs";

const oldDir = "./lingo";
const newFile = "./.lingo/metadata.json";

// Read old translations
const oldTranslations = {}; // Parse old files

// Convert to new format
const newMetadata = {
  version: "1",
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  translations: {}, // Convert old translations
};

// Write new metadata
fs.writeFileSync(newFile, JSON.stringify(newMetadata, null, 2));

これは手動作業であり、形式固有です。

オプション3: ハイブリッドアプローチ

ほとんどのテキストに対して新しい翻訳を生成
正確な表現が必要な重要な翻訳にはdata-lingo-overrideを使用

よくある問題

「モジュール'@lingo.dev/compiler'が見つかりません」 npm install @lingo.dev/compilerを実行してください

「設定は非同期関数である必要があります」(Next.js) 設定をasync functionでラップします:

export default async function () {
  return await withLingo(...);
}

「sourceLocaleが必要です」 設定にsourceLocale: "en"を追加してください。

翻訳が表示されない 以下を確認してください:

LingoProviderがルートレイアウトにあること
.lingo/metadata.jsonが存在すること
コンソールエラーがないこと

よくある質問

両方のコンパイラを同時に実行できますか? いいえ。新しいコンパイラをインストールする前に、古いコンパイラをアンインストールしてください。

翻訳は失われますか? 手動で移行すれば失われません。それ以外の場合は、AIを使用して再生成します(APIクレジットが必要です)。

フレームワークがまだサポートされていない場合は? 新しいコンパイラは現在Next.jsとViteをサポートしています。他のフレームワークは近日対応予定です。古いコンパイラを使い続けるか、フレームワークのサポートに貢献してください。

移行にはどのくらい時間がかかりますか?

シンプルなプロジェクト: 15〜30分
複雑なプロジェクト: 1〜2時間
ほとんどの時間はテストと翻訳の検証に費やされます

今すぐ移行すべきですか、それとも待つべきですか? 移行すべき場合:

新機能が必要な場合(ビルドモード、オーバーライド、カスタムリゾルバー)
新しいプロジェクトを開始する場合
より良い開発者体験が必要な場合

待つべき場合:

古いコンパイラでプロジェクトが正常に動作している場合
新しいコンパイラでまだサポートされていないフレームワークが必要な場合

次のステップ

クイックスタート — 新しいコンパイラをセットアップ
設定リファレンス — すべてのオプションを確認
ベストプラクティス — 推奨ワークフロー
トラブルシューティング — よくある問題