移行ガイド
Alpha
Lingo.dev Compiler はアルファ版です。動作は安定しておらず、本番環境での利用は推奨されません。API はリリースごとに変更される可能性があります。
このガイドでは、従来の lingo.dev compiler パッケージから現在の @lingo.dev/compiler パッケージへの移行方法を説明します。新しいパッケージでは、スコープ付きの npm 名、シンプルになった API、プラグインベースの Vite 連携、そしてメタデータ用の新しい .lingo/ ディレクトリが導入されています。
変更点の概要#
| 項目 | 変更前（lingo.dev） | 変更後（@lingo.dev/compiler） |
|---|---|---|
| パッケージ名 | lingo.dev | @lingo.dev/compiler |
| Next.js 連携 | 設定を直接変更 | withLingo() の非同期ラッパー |
| Vite 連携 | 手動設定 | lingoCompilerPlugin |
| LingoProvider | loadDictionary prop が必要 | prop 不要 |
| メタデータディレクトリ | lingo/ | .lingo/ |
| オプトインディレクティブ | 'use i18n' が必要 | 任意（デフォルトですべて翻訳） |
| import | from "lingo.dev/react" | from "@lingo.dev/compiler/react" |
移行手順#
パッケージを置き換える
古いパッケージを削除し、新しいパッケージをインストールします。
npm uninstall lingo.dev
npm install @lingo.dev/compilerimport を更新する
すべての import パスを置き換えます。
// Before
import { LingoProvider, useLingoContext } from "lingo.dev/react";
// After
import { LingoProvider, useLingoContext } from "@lingo.dev/compiler/react";Next.js の設定を更新する（該当する場合）
Next.js の設定は、非同期関数として定義する必要があります。
// Before
import { withLingo } from "lingo.dev/next";
const nextConfig = {};
export default withLingo(nextConfig, { /* options */ });
// After
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",
});
}非同期関数のラッパーは必須です。同期 export のままだとビルドは失敗します。詳しくは Next.js Integration をご覧ください。
Vite の設定を更新する（該当する場合）
手動設定は lingoCompilerPlugin に置き換えてください。
// 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"],
models: "lingo.dev",
}),
react(), // Must come AFTER lingoCompilerPlugin
],
});LingoProvider をシンプルにする
loadDictionary prop は不要になりました。compiler が辞書の読み込みを自動で処理します。
// Before
import { LingoProvider } from "lingo.dev/react";
<LingoProvider loadDictionary={loadDictionary}>
<App />
</LingoProvider>
// After
import { LingoProvider } from "@lingo.dev/compiler/react";
<LingoProvider>
<App />
</LingoProvider>メタデータディレクトリを移動する
メタデータディレクトリの名前を lingo/ から .lingo/ に変更します。
mv lingo/ .lingo/古いディレクトリ名を参照している場合は、.gitignore を更新してください。.lingo/ ディレクトリはバージョン管理にコミットする必要があります。
'use i18n' ディレクティブを更新する（任意）
新しいパッケージでは、'use i18n' は任意です。デフォルトでは、sourceRoot 内のすべてのファイルが翻訳対象になります。オプトインの挙動を維持したい場合は、設定で useDirective: true を指定してください。
{
useDirective: true, // Keep requiring 'use i18n' in each file
}useDirective を削除するか、false に設定すると、ファイル内の 'use i18n' ディレクティブも削除できます。sourceRoot 内のすべてのファイルが自動的に翻訳されます。
再ビルドして確認する
開発サーバーを起動し、翻訳が正しく表示されることを確認します。
npm run dev以下を確認してください。
- 疑似翻訳ツールが
[!!! ... !!!]マーカーを生成すること（有効な場合） - これまで翻訳されていたすべての文字列が引き続き機能すること
.lingo/metadata.jsonファイルが作成または更新されること