プロジェクト構造

.lingo/ディレクトリとその内容について理解します。

ディレクトリ概要

コンパイラを初めて実行すると、プロジェクトルートに.lingo/ディレクトリが作成されます。

your-project/
├── .lingo/
│   ├── metadata.json
│   ├── locale-resolver.server.ts (optional)
│   └── locale-resolver.client.ts (optional)
├── src/
├── package.json
└── ...

metadata.json

すべての翻訳データを含むコアファイルです。

構造

{
  "version": "1",
  "sourceLocale": "en",
  "targetLocales": ["es", "de", "fr"],
  "translations": {
    "abc123def456": {
      "source": "Welcome to our app",
      "context": {
        "file": "app/page.tsx",
        "line": 12,
        "component": "HomePage"
      },
      "locales": {
        "es": "Bienvenido a nuestra aplicación",
        "de": "Willkommen in unserer App",
        "fr": "Bienvenue dans notre application"
      },
      "metadata": {
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    }
  }
}

主要フィールド

バージョン: メタデータフォーマットのバージョン。現在: "1"

ソース/ターゲットロケール: 設定されたロケール

翻訳: すべての翻訳可能な文字列のハッシュベースマッピング:

• ハッシュ (abc123def456): ソーステキスト + コンテキストに基づく安定した識別子
• source: 元の英語テキスト
• context: このテキストが表示される場所(ファイル、行、コンポーネント)
• locales: 各ターゲットロケールの翻訳
• metadata: 翻訳が作成/更新された日時

ハッシュ生成

ハッシュは決定論的です:

• ソーステキスト + コンポーネントコンテキストに基づく
• 異なる場所の同じテキスト = 異なるハッシュ
• コンテキストを考慮した翻訳を可能にする

例:

// app/home/page.tsx
<button>Submit</button> // Hash: abc123

// app/checkout/page.tsx
<button>Submit</button> // Hash: def456 (different context)

カスタムロケールリゾルバー

ロケール検出と永続化をカスタマイズするためのオプションファイルです。

locale-resolver.server.ts

サーバーサイドのロケール検出(Next.jsのみ):

// .lingo/locale-resolver.server.ts
export async function getServerLocale(): Promise<string> {
  // Your custom logic
  return "en";
}

locale-resolver.client.ts

クライアントサイドのロケール検出と永続化:

// .lingo/locale-resolver.client.ts
export function getClientLocale(): string {
  // Detect locale
  return "en";
}

export function persistLocale(locale: string): void {
  // Save locale preference
}

これらのファイルが存在しない場合、コンパイラはデフォルトのCookieベースの動作を使用します。

詳細については、カスタムロケールリゾルバーを参照してください。

バージョン管理

.lingo/をコミットすべきですか?

はい。 .lingo/ディレクトリはバージョン管理する必要があります:

コミットするもの:

• metadata.json — すべての翻訳を含む
• カスタムロケールリゾルバー(作成した場合)

コミットしないもの:

• なし — .lingo/内のすべてのファイルをコミットする必要があります

翻訳をコミットする理由

1. バージョン管理 — コードと一緒に翻訳の変更を追跡
2. チームコラボレーション — チーム全体で翻訳を共有
3. CI/CD — 本番ビルドはコミットされた翻訳を使用
4. 監査証跡 — 翻訳がいつ、なぜ変更されたかを確認

Git統合

リポジトリに.lingo/を追加します:

git add .lingo/
git commit -m "chore: update translations"
git push

コンパイラは以下の場合に.lingo/metadata.jsonを自動的に更新します:

• 新しい翻訳可能なテキストが追加された場合
• 既存のテキストが変更された場合
• 翻訳が生成された場合

これらの更新を定期的にコミットしてください。

ファイルサイズ

metadata.jsonはアプリとともに増加します:

• 小規模アプリ(50文字列): 約10 KB
• 中規模アプリ(500文字列): 約100 KB
• 大規模アプリ(5000文字列): 約1 MB

これは正常であり、バージョン管理において許容範囲です。

クリーンアップ

未使用の翻訳を削除

時間の経過とともに、未使用の翻訳(削除されたコンポーネントからのもの)が蓄積される可能性があります。

手動クリーンアップ:

1. コードベース内でハッシュを検索
2. 見つからない場合は、metadata.jsonから削除

自動クリーンアップ(近日公開):

npx @lingo.dev/compiler clean

これにより、未使用の翻訳が自動的に削除されます。

翻訳のリセット

すべての翻訳を最初から再生成するには:

# Backup current translations
cp .lingo/metadata.json .lingo/metadata.backup.json

# Delete metadata
rm .lingo/metadata.json

# Regenerate
npm run dev # or npm run build

マイグレーション

旧コンパイラからの移行

旧コンパイラは異なるファイル構造を使用していました:

旧:

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

新:

.lingo/
└── metadata.json

マイグレーションは自動化されていません。詳細についてはマイグレーションガイドを参照してください。

翻訳の確認

エディタで表示

エディタで.lingo/metadata.jsonを開きます:

{
  "translations": {
    "abc123": {
      "source": "Welcome",
      "locales": {
        "es": "Bienvenido"
      }
    }
  }
}

翻訳の検索

ソーステキストで翻訳を検索:

grep -r "Welcome" .lingo/metadata.json

ハッシュで検索

grep -r "abc123" .lingo/metadata.json

整形表示

cat .lingo/metadata.json | jq '.'

よくある質問

metadata.jsonを手動で編集できますか? はい、ただし推奨されません。代わりにdata-lingo-overrideを使用してください。より安全で、ソースコードでバージョン管理されます。

metadata.jsonを削除するとどうなりますか? コンパイラは次回のビルド時に再生成します。すべての翻訳が新たに生成されます(APIクレジットが消費されます)。

.lingoを別のディレクトリに移動できますか？ はい。lingoDirオプションで設定できます：

{
  lingoDir: "translations"
}

metadata.jsonには機密データが含まれていますか？ いいえ。ソーステキストと翻訳のみが含まれており、APIキーやシークレットは含まれていません。

複数のブランチからmetadata.jsonをマージできますか？ はい。Gitが自動的にマージを処理します。競合はまれです（ハッシュは一意です）。

2つのブランチが同じ翻訳を追加した場合はどうなりますか？ Gitが自動的にマージします。ハッシュが異なる場合（異なるコンテキスト）、両方が保持されます。

次のステップ

• カスタムロケールリゾルバー — 永続化のカスタマイズ
• 開発ツール — 疑似翻訳ツールの使用
• ビルドモード — キャッシュ動作の理解