フォーマット

CLI は18種類のファイル形式に対応しています。形式はファイル拡張子から自動判定されますが、常に明示指定が必要な3つの形式（format、files[]、yaml-openapi）では、yaml-root-key エントリで android を設定して上書きしてください。

npx degit lingodotdev/lingo.dev/demo/new-cli my-lingo-demo
cd my-lingo-demo

JSON と JSONC#

シンプルなキー/値形式の翻訳です。key control で別途指定しない限り、すべての文字列値が翻訳されます。

{ "pattern": "content/en/app.json", "lockedKeys": ["meta.version"] }

JSONCではコメントも保持され、エンジンがそれをコンテキストとして読み取ります — 詳しくは translator notes を参照してください。

{ "pattern": "content/en/settings.jsonc", "preservedKeys": ["featureFlags"] }

Markdown、MDX、Markdoc#

本文のテキストはデフォルトで翻訳されます。frontmatter と埋め込みコンポーネントは、明示的に有効化しない限り翻訳されません。

Frontmatter#

translateFrontmatterFields で、翻訳対象にする frontmatter フィールドを指定します。

{
  "pattern": "content/en/guide.md",
  "translateFrontmatterFields": ["title", "description"]
}

MDX コンポーネントのprops#

MDXでは、特定のコンポーネント上の特定のpropsを translateComponentProps で翻訳対象にできます。

{
  "pattern": "content/en/landing.mdx",
  "translateFrontmatterFields": ["title"],
  "translateComponentProps": [{ "component": ["Hero", "Callout"], "props": ["title", "body"] }]
}

これにより、title と body 上の <Hero> および <Callout> props が翻訳され、それ以外のpropsは変更されません。

Markdoc#

MarkdocはMarkdownと同様に動作し、frontmatter とタグ属性を保持します。

{
  "pattern": "content/en/changelog.mdoc",
  "translateFrontmatterFields": ["title"]
}

YAML#

汎用YAMLは .yaml/.yml から自動判定されます。すべての文字列値が翻訳され、キーと構造は保持されます。

{ "pattern": "content/en/strings.yaml" }

OpenAPI仕様は例外です。同じ .yaml 拡張子を使いますが、format を明示的に指定する必要があります。これにより、エンジンは人が読むフィールド（summary、description）のみを翻訳し、スキーマキー、path、operation ID はそのまま保持します。

{ "pattern": "content/en/api.yaml", "format": "yaml-openapi" }

Rails スタイルのロケールファイルも、もう1つの特殊なケースです。ロケールが YAML のルートキー（en:）となり、出力先ファイルも対象のロケール（es:）をルートにする必要があります。これらも format を明示的に設定してください。

{ "pattern": "config/locales/en.yml", "format": "yaml-root-key" }

アプリ / フレームワーク向けフォーマット#

PO、Flutter ARB、Xcode .strings、Xcode .stringsdict、TypeScriptロケールモジュール、XLIFF、SubRip、PHP は、いずれも同じルールです。翻訳可能なテキストだけを翻訳し、構造に関わる要素はそのまま保持します（キー、ID、メタデータ、プレースホルダー、タイムコード、コード、書式など）。どれも拡張子から自動判定されるので、ソースファイルにパターンを向けるだけで使えます。

{ "pattern": "lib/l10n/app_en.arb" }
{ "pattern": "locales/en.po" }
{ "pattern": "Localizable.strings" }
{ "pattern": "l10n/en.xlf" }

ただし1つだけ、拡張子が曖昧で自動判定できないため、format の明示指定が必要な形式があります。

{ "pattern": "res/values/strings.xml", "format": "android" }

Xcode String Catalogs#

.xcstrings（String Catalog）ファイルには、すべてのロケールが1つのファイルに入っています。ロケールごとの出力パスはなく、CLIはソースロケールを読み取り、すべてのターゲットを同じファイルに書き戻します。

{ "pattern": "Localizable.xcstrings" }

カタログ内で"shouldTranslate": falseのフラグが付いた文字列はスキップされ、CLIによって未翻訳のまま変更されません。

キースコープを使える形式は？#

lingo push --key は、指定したキーだけを再翻訳し、それ以外には手を加えません。使うには、安定した名前を持つキーと、特定のキーを含まなくても成立するファイルが必要です。そのため、ドキュメント形式と複数形辞書は対象外です。

md、mdx、markdoc、html、srt、yaml-openapi では、各ユニットはドキュメント内の位置 — セクション番号、ノードパス、字幕キュー番号など — で特定されます。つまり、その上位にある要素が少しでも編集されるとキーが変わってしまい、特定のユニットを狙ったスコープでも別の文字列を選んでしまうか、何も選べなくなります。xcode-stringsdict が対象外になるのは逆の理由です。こちらのキーは複数形カテゴリそのもので、有効な複数形辞書として成立させるために必須なので、省くことはできません。

lingo push は、キー指定の実行中に対象外のファイルがあっても処理全体を失敗にはせず、警告を出してそのファイルだけを除外します。そのため、push ではそれらをキーバリュー形式のファイルと一緒に混在させることはできます。これらを push する場合は、--key を付けないでください。

対応している形式の中でも、位置ベースのメンバーは同じ扱いになります。配列要素、Android の <string-array> 項目、<plurals> の quantity では、スコープ内でもソーステキストがそのまま維持されます。

出力パス#

このパターンで指定するのはソースファイルです。各ターゲットパスは、そこから導き出されます。ルールは次の 4 つで、上から順に適用されます。

1. パスセグメント全体またはファイル名全体がロケールになっている場合 — これが一般的なケースです。content/en/app.json → content/de/app.json、locales/en.json → locales/de.json。
2. セグメントやファイル名の末尾にロケールが付く場合。この形式を採用しているのは、Android、Xcode の .strings/.stringsdict、Flutter、そして yaml-root-key です。res/values-en/ → res/values-de/、app_en.arb → app_de.arb、devise.en.yml → devise.de.yml。
3. デフォルト言語用にプラットフォームが予約している名前が使われていて、パス内にロケールがまったく含まれない場合。 Android の res/values/ は res/values-de/ になり、Xcode の Base.lproj は de.lproj になります。
4. String Catalog。1 つのファイルですべてのロケールを保持するため、ターゲットパスはソースパスと同じです。

Android だけは、ターゲットパスが BCP 47 にならない唯一のプラットフォームです。CLI は Android が実際に読み取るリソース修飾子を書き出すため、pt-BR は values-pt-rBR/ に、zh-Hans は values-b+zh+Hans/ に出力されます。

どのルールにも当てはまらない場合 — つまりソースロケールがパス内のどこにも現れない場合 — CLI はフォールバックとして、ファイルの横に <locale>/ ディレクトリを作成し、lingo push で推測によるものだと知らせます。この警告が出たら、パターンが誤っているサインです。Configuration を参照してください。

legacy CLI から移行する場合#

legacy CLI で対応していた形式の多くは、現在のCLIでも利用できます（PO、XLIFF、Android/Xcode strings、Flutter ARB など — 上の表を参照）。一方で、あまり一般的でない一部の形式（例: CSV、HTML、MJML、.properties）はまだ未対応です。必要な形式が追加されるまでは、legacy CLI docs を参照してください。