Lingo.dev のCLIは、リポジトリ内の静的ファイル（Markdown、MDX、Markdoc、JSON、YAML、字幕など）を、設定済みのローカライゼーションエンジンを通じて翻訳します。コンテンツを指定して一度実行するだけで、翻訳済みファイルがソースと並んで生成されます。
対応コンテンツタイプ#
| コンテンツタイプ | 形式 | CLIバケット | パス例 |
|---|---|---|---|
| ドキュメント | Markdown | markdown | docs/[locale]/getting-started.md |
| ドキュメント | MDX | mdx | docs/[locale]/getting-started.mdx |
| ドキュメント | Markdoc | markdoc | docs/[locale]/getting-started.mdoc |
| 構造化データ | JSON | json | data/[locale].json |
| 構造化データ | YAML | yaml | data/[locale].yaml |
| ブログ記事 | Markdown / MDX | markdown / mdx | blog/[locale]/post-slug.md |
| 字幕 | SRT | srt | subs/[locale]/intro.srt |
| 字幕 | VTT | vtt | subs/[locale]/intro.vtt |
| スプレッドシート | CSV | csv-per-locale | data/[locale].csv |
| 設定文字列 | Properties | properties | lang/[locale].properties |
| 設定文字列 | Gettext PO | po | locale/[locale]/messages.po |
| プレーンテキスト | TXT | txt | content/[locale]/readme.txt |
前提条件#
CLI を実行するたびに、コンテンツはローカライゼーションエンジンを通過します。これは、適用する LLM モデル、用語集、ブランドボイス、指示を決める設定です。Lingo.dev ダッシュボードで作成し、API キーを生成してください。
ドキュメントサイト#
多くのドキュメントフレームワークでは、翻訳済みコンテンツをロケールごとのディレクトリで管理します。CLI のmarkdown、mdx、markdocバケットなら、frontmatter、コードブロック、コンポーネント構文を保ったまま、これらのファイルを翻訳できます。
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "de", "ja"]
},
"buckets": {
"markdown": {
"include": ["docs/[locale]/getting-started.md"]
},
"mdx": {
"include": ["docs/[locale]/setup.mdx"]
}
}
}お使いのフレームワークのディレクトリ規約に合わせて、includeパターンを調整してください。
| フレームワーク | ロケールディレクトリ規約 | 参考リンク |
|---|---|---|
| Docusaurus | i18n/[locale]/docusaurus-plugin-content-docs/current/ | Docusaurus i18n ガイド |
| Nextra | ロケールごとのページまたは JSON 辞書 | Nextra ドキュメント |
| Hugo | content/[locale]/ | Hugo 多言語ガイド |
| Astro | src/content/[locale]/ または JSON 辞書 | Astro i18n ガイド |
| VitePress | [locale]/ ディレクトリプレフィックス | VitePress i18n |
| MkDocs | i18n プラグインを使ったロケールごとのdocs/ | MkDocs i18n プラグイン |
MDX コンポーネント
mdxバケットは、翻訳時も JSX コンポーネント構文を保持します。<Callout>、<Tabs>、<CodeBlock>のようなカスタムコンポーネントはそのまま維持され、内部のテキストコンテンツだけが翻訳されます。
構造化データ#
JSON と YAML ファイルは、jsonおよびyamlバケットで翻訳できます。翻訳不要な値（ID、URL、設定フラグ）を変更させたくない場合は、locked keysを使ってください。
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "de", "ja"]
},
"buckets": {
"json": {
"include": ["content/[locale].json"],
"lockedKeys": ["id", "slug", "url"]
},
"yaml": {
"include": ["data/[locale].yaml"]
}
}
}ルートキーにロケールコードを使う YAML ファイル（Rails や Hugo で一般的）では、代わりにyaml-root-keyバケットを使用してください。このバケットはソースロケールキーから読み取り、同じファイル内のターゲットロケールキーに書き込みます。
字幕#
SRT と VTT の字幕ファイルは、srtおよびvttバケットで翻訳できます。CLI はタイミングデータ、キューインデックス、書式タグをすべて保持し、翻訳されるのはテキストコンテンツだけです。
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "de", "ja"]
},
"buckets": {
"srt": {
"include": ["subs/[locale]/intro.srt"]
}
}
}大規模なコンテンツを扱う#
静的コンテンツのリポジトリには、数千ものファイルが含まれることがあります。CLI は次の 3 つの仕組みで、これを効率よく処理します。
| 仕組み | 効果 |
|---|---|
| Lockfile | ソースコンテンツの SHA-256 フィンガープリントを追跡します。2 回目以降の実行では、新規または変更されたファイルだけが翻訳対象になります。 |
| 並列処理 | 翻訳処理を複数のワーカーに分散して同時実行します。run --concurrency 20で設定できます。 |
| 対象を絞った実行 | 特定のバケットやロケールだけを処理できます: run --bucket markdown または run --target-locale es。 |
