静的コンテンツのローカライズ

Lingo.dev のCLIは、リポジトリ内の静的ファイル（Markdown、MDX、Markdoc、JSON、YAML、字幕など）を、設定済みのローカライゼーションエンジンを通じて翻訳します。コンテンツを指定して一度実行するだけで、翻訳済みファイルがソースと並んで生成されます。

対応コンテンツタイプ#

CLI は各ファイルの形式を拡張子から自動判別するため、bucket type の設定は不要です。ロケールはパスに含まれるため（content/en/x.md は content/de/x.md になります）、[locale] プレースホルダーも必要ありません。

対応ファイル形式の一覧は、formats リファレンスをご覧ください。

前提条件#

実行のたびに、コンテンツはローカライゼーションエンジンを通ります。これは、どのLLMモデル、用語集、ブランドボイス、ルールを適用するかを決める設定です。まずはLingo.devのダッシュボードで作成し、続いてCLI（Node 22+）をセットアップしてください。

npm install -g @lingo.dev/cli
lingo login
lingo init
lingo link

lingo init と lingo link を実行すると .lingo/config.json が作成され、CLI が組織とエンジンに接続されます。すべての環境で同じ設定を共有できるよう、このファイルはコミットしてください。

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "docs/en/getting-started.md" }]
}

CI では lingo login をスキップし、代わりに LINGO_API_KEY を環境変数として指定してください。これは API keys から生成できます。

ドキュメントサイト#

多くのドキュメントフレームワークでは、翻訳済みコンテンツをロケールごとのディレクトリで管理します。ソースファイルごと（または glob）にパターンを files へ追加してください。CLI は Markdown、MDX、Markdoc を翻訳しつつ、frontmatter、コードブロック、コンポーネント構文はそのまま保持します。

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    { "pattern": "docs/en/getting-started.md" },
    { "pattern": "docs/en/setup.mdx" }
  ]
}

まずは最初の翻訳を実行して、すべての対象ロケールを埋めましょう。

lingo push --backfill-missing

以降の実行では、lingo push が変更のあった箇所だけを翻訳します。別の場所で生成された翻訳を取り込むには、lingo pull を使ってください。

使用中のフレームワークのディレクトリ規約に合わせて、ソースパスを調整してください。

構造化データ#

JSON と YAML ファイルは、拡張子に応じて自動的に翻訳されます。翻訳対象ではない値（ID、URL、設定フラグ）を変更しないようにするには、key controls を使ってください。

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    { "pattern": "content/en.json" },
    { "pattern": "data/en.yaml" }
  ]
}

汎用 YAML ではformatフィールドは不要です。ファイルエントリで明示的なyaml-openapiが必要なのは、yaml-root-key、android、"format"のみです。

字幕#

SRT 字幕ファイルは拡張子から自動的に判別されて翻訳されます。CLI はタイミングデータ、キューインデックス、書式タグをすべて保持し、翻訳するのはテキストだけです。

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "subs/en/intro.srt" }]
}

大規模なコンテンツを扱う#

静的コンテンツのリポジトリには数千ものファイルが含まれることがあります。CLI はそうした規模でも効率よく処理できます。

翻訳が最新かどうかをファイルを書き出さずに確認したい場合—CI のゲートにも便利です—は、lingo check を実行してください。

次のステップ#