ロケールごとのCSV

Lingo.dev CLIを使用したロケール別ファイルによるCSVファイルのAI翻訳

ロケールごとのCSVとは？

ロケールごとのCSVは、すべてのロケールを複数の列を持つ単一のCSVファイルに保存するのではなく、各ロケールが独自の個別のCSVファイルを持つ翻訳アプローチです。この形式は、各行がレコードを表し、列が異なるフィールドを表す複数の列を持つ構造化データ（製品カタログ、ユーザーデータ、コンテンツ管理システムなど）がある場合に便利です。

例：

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3

すべてのロケールをKEY,en,esのような列で1つのファイルに保存する標準的なCSVバケットとは異なり、csv-per-localeバケットは各ロケールごとに個別のファイルを維持し、すべての列を含む元のCSV構造を保持します。

Lingo.dev CLIとは？

Lingo.dev CLIは、AIを使用してアプリやコンテンツを翻訳するための無料のオープンソースCLIです。従来の翻訳管理ソフトウェアを置き換えながら、既存のパイプラインと統合するように設計されています。

詳細については、概要を参照してください。

このガイドについて

このガイドでは、Lingo.dev CLIでcsv-per-localeバケットを使用してCSVファイルを翻訳する方法を説明します。

以下の方法を学習します：

  • ゼロからプロジェクトを作成する
  • ロケールごとに個別のCSVファイルを使用した翻訳パイプラインを設定する
  • AIで翻訳を生成する
  • ロックされたキーと無視されたキーを使用する

前提条件

Lingo.dev CLIを使用するには、Node.js v18以降がインストールされていることを確認してください：

❯ node -v
v22.17.0

ステップ1. プロジェクトをセットアップする

プロジェクトのディレクトリに、i18n.jsonファイルを作成します：

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

このファイルは、翻訳する言語とファイルシステム上のローカライズ可能なコンテンツの場所を含む、翻訳パイプラインの動作を定義します。

利用可能なプロパティの詳細については、i18n.jsonを参照してください。

ステップ2. ソースロケールを設定する

_ソースロケール_は、コンテンツが記述された元の言語と地域です。ソースロケールを設定するには、i18n.jsonファイルのlocale.sourceプロパティを設定します。

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

ソースロケールはBCP 47言語タグとして指定する必要があります。

Lingo.dev CLIがサポートするロケールコードの完全なリストについては、サポートされているロケールコードを参照してください。

ステップ3. ターゲットロケールを設定する

_ターゲットロケール_は、コンテンツを翻訳したい言語と地域です。ターゲットロケールを設定するには、i18n.jsonファイルのlocale.targetsプロパティを設定します。

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

ステップ4. ソースコンテンツを作成する

まだ作成していない場合は、ソースロケール用のCSVファイルを作成します。ファイルには以下を含める必要があります。

  • 列名を含むヘッダー行
  • 1つ以上のデータ行
  • 必要な任意の列(特定の列名に限定されません)

CSVファイルは、パスのどこかにソースロケールを含む場所に配置する必要があります(例: en/のようなディレクトリ名、またはdata.en.csvのようなファイル名の一部として)。

注意: 標準のCSVバケットとは異なり、「KEY」列やソースロケールに一致する列は必要ありません。csv-per-localeバケットは各行をレコードとして扱い、構造を保持しながらCSV内のすべてのテキストコンテンツを翻訳します。

ステップ5. バケットを作成する

  1. i18n.jsonファイルで、bucketsオブジェクトに"csv-per-locale"オブジェクトを追加します:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {}
  }
}

  2. "csv-per-locale"オブジェクトで、1つ以上のincludeパターンの配列を定義します:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"]
    }
  }
}

    これらのパターンは、翻訳するファイルを定義します。

    パターン自体:

    • 設定されたロケールのプレースホルダーとして[locale]を含む必要があります
    • ファイルパスを指定できます(例: "[locale]/data.csv")
    • ワイルドカードプレースホルダーとしてアスタリスクを使用できます(例: "[locale]/*.csv")

    再帰的なglobパターン(例: **/*.csv)はサポートされていません。

  3. オプションで、lockedKeysとignoredKeysを設定できます:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}
    • lockedKeys: 翻訳すべきでないキー(最初の列の列値、通常はID)
    • ignoredKeys: ターゲットロケールファイルに表示すべきでないキー

ステップ6. LLMを設定する

Lingo.dev CLIは、大規模言語モデル(LLM)を使用してAIでコンテンツを翻訳します。これらのモデルのいずれかを使用するには、サポートされているプロバイダーからAPIキーが必要です。

できるだけ早く開始するには、Lingo.dev Engineの使用をお勧めします。これは、毎月10,000トークンの無料使用量を提供する当社独自のホスト型プラットフォームです:

  1. Lingo.devアカウントにサインアップします。

  2. 次のコマンドを実行します:

    npx lingo.dev@latest login

    これにより、デフォルトのブラウザが開き、認証を求められます。

  3. プロンプトに従います。

ステップ7. 翻訳を生成する

i18n.jsonファイルを含むディレクトリで、次のコマンドを実行します:

npx lingo.dev@latest run

このコマンドは以下を実行します:

  1. i18n.jsonファイルを読み込みます。
  2. 翻訳が必要なファイルを検出します。
  3. CSVファイルから翻訳可能なコンテンツを抽出します。
  4. 設定されたLLMを使用して抽出されたコンテンツを翻訳します。
  5. 翻訳されたコンテンツを各ターゲットロケール用の個別のCSVファイルに書き込みます。

翻訳が初めて生成される際、i18n.lockファイルが作成されます。このファイルは翻訳済みのコンテンツを追跡し、以降の実行時に不要な再翻訳を防ぎます。

例

en/example.csv(翻訳前)

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3
4,Success,Operation completed successfully,2024-01-01,true,4
5,Loading,Please wait while we load your data,2024-01-01,true,5

es/example.csv(翻訳後)

id,name,description,created,enabled,sort
1,Bienvenida,Bienvenido a nuestra aplicación,2024-01-01,true,1
2,Guardar,Guarda tus cambios,2024-01-01,true,2
3,Error,Ha ocurrido un error,2024-01-01,true,3
4,Éxito,Operación completada con éxito,2024-01-01,true,4
5,Cargando,Por favor espera mientras cargamos tus datos,2024-01-01,true,5

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}

i18n.lock

version: 1
checksums:
  e8b273672f895de0944f0a2317670d7c:
    0/name: 1308168cca4fa5d8d7a0cf24e55e93fc
    0/description: 8de4bc8832b11b380bc4cbcedc16e48b
    1/name: f7a2929f33bc420195e59ac5a8bcd454
    1/description: 8de4bc8832b11b380bc4cbcedc16e48b
    2/name: d3d99b147cc363dc6db8a48e8a13d4c1
    2/description: 7cd986af1fe5e89abe7ecffba5413110

CSVバケットとの違い

csv-per-localeバケットは、標準のcsvバケットといくつかの点で異なります:

  • ファイル構造: csv-per-localeは各ロケール用に個別のファイルを使用します(例: en/example.csv、es/example.csv)。一方、csvは複数の列を持つ単一のファイルを使用します(例: KEY,en,es)。

  • 列の要件: csv-per-localeは「KEY」列やロケール名の列を必要としません。データに適した任意の列構造を使用できます。

  • ユースケース: csv-per-localeは、製品カタログ、コンテンツ管理システム、データベースなど、各行が複数のフィールドを持つレコードを表す構造化データに最適です。標準のcsvバケットは、シンプルなキーバリュー形式の翻訳テーブルに適しています。

  • ファイルの変更: 両方のバケットはファイルを直接変更しますが、csv-per-localeは各ロケール用に個別のファイルを作成するのに対し、csvは既存のファイルに新しい列を追加します。