アルファ
Lingo.dev Compiler はアルファ版です。動作はまだ安定しておらず、本番環境での利用は推奨していません。API はリリースごとに変更される可能性があります。
ここで紹介するベストプラクティスは、Lingo.dev Compiler で信頼性が高く、コスト効率にも優れた結果を得るための実践パターンです。ビルドパイプライン、コード構成、翻訳品質、テストをカバーしています。
ビルドパイプライン#
3つのモードを使い分ける#
開発 - pseudotranslator
即時にフィードバックを得るには dev.usePseudotranslator: true を有効にします。API 呼び出しは不要、コストもかからず、結果もすぐに確認できます。疑似翻訳を使えば、未翻訳の文字列を見つけたり、レイアウトを検証したりできます。
{
buildMode: "translate",
dev: { usePseudotranslator: true },
}CI - 翻訳モード
buildMode: "translate" と実際のプロバイダーを使って実行します。各 CI 実行後に更新された .lingo/metadata.json をコミットして、本番環境でも翻訳を利用できるようにしてください。
LINGO_BUILD_MODE=translate npm run build本番 - cache-only モード
buildMode: "cache-only" でデプロイします。本番環境で API キーは不要です。ビルドは決定的で高速に実行できます。
LINGO_BUILD_MODE=cache-only npm run buildバージョン管理#
.lingo/ をリポジトリにコミットする#
.lingo/metadata.json ファイルは、キャッシュされたすべての翻訳の信頼できる唯一の情報源です。cache-only モードでの本番ビルドはこれに依存します。
# .gitignore - do NOT ignore .lingo/
node_modules/
dist/
.env.lingo/metadata.json がコミットされていないと、cache-only モードでは読み込める翻訳がないため、本番ビルドは失敗します。
翻訳差分をレビューする#
CI が翻訳の更新をコミットしたら、プルリクエストで .lingo/metadata.json の差分をレビューしてください。これにより、本番環境に反映される前に翻訳上の問題を見つけられます。コード変更をレビューするのと同じ感覚です。
コード構成#
翻訳対象のテキストは JSX に直接書く#
Compiler は JSX をスキャンして翻訳可能なコンテンツを検出します。JavaScript の変数、定数、外部ファイルに置かれたテキストは検出されません。
// Good - compiler detects this text
export function Header() {
return <h1>Welcome to our app</h1>;
}
// Bad - compiler cannot detect text in a variable
const title = "Welcome to our app";
export function Header() {
return <h1>{title}</h1>;
}大規模なコードベースでは useDirective を使う#
大規模なプロジェクトでは、すべてのファイルをスキャンするとビルド時間が伸びます。useDirective: true を有効にし、ユーザー向けテキストを含むファイルにだけ 'use i18n' を追加してください。
{
useDirective: true,
}'use i18n';
// Only this file is scanned for translations
export function PublicPage() {
return <h1>Welcome</h1>;
}sourceRoot は必要最小限に絞る#
sourceRoot は、翻訳対象のコンポーネントを含む最小のディレクトリに設定してください。広すぎる sourceRoot だと不要なファイルまでスキャンしてしまいます。
| プロジェクトタイプ | 推奨される sourceRoot |
|---|---|
| Next.js App Router | "./app" |
| Vite + React | "src" |
| モノレポ（useDirective 使用時） | "." |
翻訳品質#
ブランド用語には手動オーバーライドを使う#
ブランド名、製品名、法的文言には、AI 翻訳に任せるのではなく manual overrides を使うべきです。
<h1 data-lingo-override={{ es: "Motor de Localizacion", de: "Lokalisierungs-Engine" }}>
Localization Engine
</h1>コスト最適化にはロケールペアのマッピングを使う#
モデルごとに得意分野も価格帯も異なります。高価なモデルは本当に必要な言語に割り当て、それ以外ではコスト効率のよいモデルを使いましょう。
{
models: {
"*:*": "groq:llama-3.3-70b-versatile", // Fast, cost-effective default
"*:ja": "anthropic:claude-3-5-sonnet", // Higher quality for Japanese
"*:zh-Hans": "anthropic:claude-3-5-sonnet", // Higher quality for Chinese
},
}用語集とブランドボイスには Lingo.dev のエンジンを使う#
アプリ全体で用語の一貫性を保ちたい場合は、Lingo.dev 上で ローカライゼーションエンジン に glossary と ブランドボイス を設定してください。これらはすべての翻訳リクエストに自動で適用されます。
複数形処理#
不要なら複数形処理を無効にする#
アプリで数値の件数をテキストと一緒に表示しない場合は、ビルドの複雑さを抑えるために複数形処理を無効にしてください。
{
pluralization: { enabled: false },
}件数に応じたテキストは自然に書く#
複数形処理が有効な場合は、数値変数を含むテキストを自然な形で記述してください。Compiler が ICU MessageFormat への変換を処理します。
// Good - the compiler detects and pluralizes this
<p>You have {count} items in your cart</p>
// Also good - works with any numeric expression
<p>{unreadCount} unread messages</p>テスト#
まず pseudotranslator でテストする#
実際の翻訳を生成する前に、pseudotranslator を使って翻訳対象を漏れなくカバーできているか確認してください。
dev.usePseudotranslator: trueを有効にする- すべてのページとコンポーネントを確認する
[!!! ... !!!]マーカーの付いていないテキストは翻訳されていません- テキスト配置の問題を修正する（テキストを JSX 内に移動する、
sourceRootを調整する、'use i18n'ディレクティブを追加する）
未翻訳の文字列は、実際の翻訳を生成した後で気づくよりも、pseudotranslator で先に見つけるほうが速くて低コストです。
リリース前に実際の翻訳でテストする#
リリース前に pseudotranslator を無効にし、少なくとも1つの対象ロケールに対して実際の翻訳を生成してください。
{
dev: { usePseudotranslator: false },
}レイアウト崩れ、テキストの切れ、双方向テキストの問題など、疑似翻訳では見つけられない点を確認してください。
