Alpha
Lingo.dev Compiler はアルファ版です。動作はまだ安定しておらず、本番環境での利用は推奨されません。API もリリースごとに変更される可能性があります。
Lingo.dev Compiler は、翻訳メタデータとキャッシュを保存する .lingo/ ディレクトリをプロジェクトルートに作成し、継続的に管理します。この構成を把握しておくと、翻訳をバージョン管理しやすくなり、不足している翻訳の原因調査やビルド性能の最適化にも役立ちます。
.lingo/ ディレクトリ#
このディレクトリは初回ビルド時にコンパイラが自動で作成します。ビルドパイプラインで使われる翻訳メタデータは、すべてここに格納されます。
.lingo/
metadata.json # Translation cache and content hashes
locale-resolver.server.ts # Optional: custom server-side locale resolver
locale-resolver.client.ts # Optional: custom client-side locale resolvermetadata.json#
これは .lingo/ ディレクトリ内の中心となるファイルです。以下の情報を保存します。
- コンテンツハッシュ - 各翻訳対象文字列に対応する、安定したハッシュベースの識別子
- キャッシュされた翻訳 - 各ロケールの組み合わせごとに生成された翻訳
- ソーステキストのスナップショット - 翻訳時点のソーステキスト。変更の検出に使われます
コンパイラは各ビルドの開始時にこのファイルを読み込みます。ハッシュが一致する文字列にはキャッシュ済みの翻訳が再利用され、ハッシュが変わった、または存在しない文字列は、設定された翻訳プロバイダーに送られます。
バージョン管理にコミットする
.lingo/metadata.json は必ずリポジトリにコミットしてください。cache-only モードの本番ビルドでは、このファイルだけを参照して翻訳を読み込みます。コミットされていないと、本番ビルドは失敗します。
.gitignore の注意点#
.lingo/ を .gitignore に追加しないでください。このディレクトリはバージョン管理の対象に含める必要があります。Compiler を使うプロジェクトでは、一般的に .gitignore は次のようになります。
# Do NOT ignore .lingo/ - it contains translation cache
node_modules/
dist/
.envsourceRoot#
sourceRoot オプションで、コンパイラが翻訳対象の React コンポーネントをスキャンするディレクトリを指定します。
{
sourceRoot: "./app", // Next.js App Router
// or
sourceRoot: "src", // Vite + React
}コンパイラは sourceRoot 配下にある .tsx、.ts、.jsx、.js ファイルを再帰的にスキャンし、翻訳対象の JSX コンテンツを検出します。このディレクトリ外のファイルは処理されません。
| sourceRoot の値 | スキャン対象 |
|---|---|
"./app" | app/ ディレクトリ内のすべてのファイル（Next.js の慣例） |
"src" | src/ ディレクトリ内のすべてのファイル（Vite の慣例） |
"." | プロジェクトルート内のすべてのファイル（共有パッケージを含むモノレポで便利） |
sourceRoot を広く設定するほどスキャン対象のファイルが増え、ビルド時間も長くなります。できるだけ狭く指定してください。翻訳が必要なのが一部のファイルだけなら、代わりに useDirective オプションを使うとよいでしょう。
'use i18n' を使ったオプトインモード#
デフォルトでは、コンパイラは sourceRoot 内の JSX テキストをすべて翻訳します。オプトインモードに切り替えるには、useDirective: true を設定します。
{
useDirective: true,
}オプトインモードでは、先頭に 'use i18n' ディレクティブがあるファイルだけが処理されます。
'use i18n';
export function Welcome() {
return <h1>Welcome to our app</h1>;
// This text IS translated
}ディレクティブのないファイルはスキップされます。
export function InternalAdmin() {
return <h1>Admin Dashboard</h1>;
// This text is NOT translated
}オプトインモードを使うべきケース#
| シナリオ | 推奨モード |
|---|---|
| すべてのコンテンツを翻訳したい小規模アプリ | デフォルト（useDirective: false） |
| ユーザー向けページが一部しかない大規模コードベース | オプトイン（useDirective: true） |
| 内部向け・外部向けコンポーネントが混在するモノレポ | オプトイン（useDirective: true） |
| 段階的な導入 - 既存アプリに i18n を追加する場合 | オプトイン（useDirective: true） |
lingoDir#
lingoDir オプションを使うと、メタデータディレクトリの保存場所を変更できます。
{
lingoDir: ".lingo", // Default
// or
lingoDir: ".translations", // Custom location
}これは、.lingo/ がプロジェクト内の既存ディレクトリと競合する場合に便利です。
