CLI の設定

.lingo/config.json でソースの検出方法、翻訳オプション、翻訳先のパスを定義します。

.lingo/config.json は、プロジェクトで翻訳するファイルと翻訳先の配置場所を定義します。CLI は作業ディレクトリから上位の階層に向かって最も近い設定ファイルを探し、そのルートを基準にプロジェクトの相対パスを解決します。設定ファイルがない場合、ローカルのカタログコマンドは現在の作業ディレクトリを使用します。

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "locales/en.json" }]
}

link を実行して、リモート翻訳に必要な組織とローカライゼーションエンジンの識別子を追加します。抽出では、これらの識別子がなくてもローカルで i18n の設定を使用できます。厳密な JSON 形式で記述してください。コメントや末尾のカンマは使用できません。

ルートフィールド #

フィールド意味
orgId, engineId空でないリソース識別子。この二つでリモートとの紐付けを構成します。
sourceLocaleソースロケールを示す空でない文字列。
targetLocales空でない文字列のエントリ。実行時に重複とソースロケールに完全一致するものを除去します。
files以下で説明するソースエントリ。
i18n.messagesPath抽出、チェック、クリーンアップ用のカタログディレクトリ。既定値は locales。
i18n.typesPath抽出、チェック用の宣言ファイルのパス。既定値は lingo.d.ts。
github.workflows.onPushToDefaultBranch.enabled既定ブランチの連携トリガー。任意指定。
github.workflows.onPullRequest.enabledプルリクエストの連携トリガー。任意指定。
github.safety.requireApproval連携の実行承認設定。任意指定。

ルートやファイルエントリに不明なキーがあると、警告が表示され、そのキーは無視されます。スペルを間違えてもファイル全体は拒否されず、代わりに既定値が適用されたままになる場合があります。

初期化ではローカライゼーション設定を書き込み、リンクでは紐付け用の識別子を書き込み、リンク解除ではその識別子だけを削除します。これらの書き込み処理では他のルートセクションが保持されますが、init --force はファイルエントリを再構築するため、詳細オプションが失われます。GitHub の設定だけではアプリはインストールされず、CLI のプッシュでリポジトリの自動化が起動するようにもなりません。連携のセットアップを行ってください。

ファイルエントリのフィールド #

フィールド意味
pattern空でないソースパターンを一つ指定します。
includeソースパターン。空の場合でも pattern より優先されます。
excludeこのエントリから除外するパターン。
format以下の対応形式一覧から明示的に指定する形式。
localeFormatbcp47、underscore、または android のパス表現。
targetPath, sourceRoot出力テンプレートと、[path] 用に除去する任意指定のプレフィックス。
translateFrontmatterFieldsマークダウン系のハンドラーで選択するメタデータフィールド。
translateComponentPropsプロパティ名、またはコンポーネントで絞り込むプロパティルール。
lockedKeys, preservedKeys, ignoredKeys対応ハンドラーで使用する、空でないキーパス配列。
injectLocale真偽値または { "enabled": true, "key": "language" }。
keyColumnCSV のみ。キー列のヘッダー。既定値は最初のヘッダーセル。
lockedPatternsプロパティ形式のみ:値に含まれるRE2正規表現は翻訳せず、そのまま保持します。

各エントリには pattern または include が必要です。空の include を指定すると、何も選択されません。最初に一致したエントリのオプションが適用されます。値の管理主体と形式ごとの適用範囲については、キーの制御で説明しています。

ファイルパターン #

パターン照合では、セグメント内で *、複数のディレクトリにまたがる照合で **/ を使用できます。サブツリーを再帰的に指定するには docs/en/**/* を使用してください。末尾の ** だけでは同じ意味になりません。波括弧や拡張グロブの動作が、他のグロブライブラリと同じとは限りません。

json
{
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "files": [
    {
      "include": ["docs/en/**/*.md", "docs/en/**/*.mdx"],
      "exclude": ["docs/en/private/**/*"]
    }
  ]
}

除外は、そのエントリだけに適用されます。別のエントリでは、同じファイルを含めることができます。検出時には .git と node_modules がスキップされますが、.gitignore 内のすべてがスキップされるわけではありません。プッシュの位置引数で指定したパターンは、設定済みソースのうち、そのパターンにも一致するものだけに対象を絞り込み、計画モードを変更します。シェルでは引用符で囲んでください。

形式の選択 #

設定されている形式は、json、jsonc、md、mdx、markdoc、yaml-openapi、po、flutter、xcode-strings、yaml、android、typescript、xcode-xcstrings、srt、xliff、xcode-stringsdict、php、yaml-root-key、html、txt、csv、propertiesです。

拡張子推定される形式
.json、.jsoncJSON または JSONC。
.md、.mdx、.mdocマークダウン、MDX、Markdoc。
.html、.htmHTML。
.po、.arbGettext、Flutter。
.strings、.xcstrings、.stringsdict対応するアップルの形式。
.ts、.mts、.ctsTypeScript。
.srt, .xlf, .xliff, .phpSubRip、XLIFF、PHP。
.txtプレーンテキスト。パターンの末尾が .txt の場合、または形式が txt の場合のみ。
.csvCSV。パターンの末尾が .csv の場合、または形式が csv の場合のみ。
.propertiesJavaプロパティ形式。パターンが.propertiesまたはproperties形式で終わる場合のみ。
.yaml、.ymlyaml、yaml-root-key、または yaml ベースの OpenAPI を明示的に設定してください。
.xmlandroid を明示的に設定してください。汎用 XML には対応していません。

OpenAPIの正確な識別子はyaml-openapiです。形式を明示的に選択しても、ファイル検出でサポートされる拡張子の制限は適用されます。.txt、.csv、.propertiesのファイルが対象となるのは、パターンがその拡張子で終わるエントリ、または対応する形式としてtxt、csv、propertiesを設定したエントリのみです。これらのエントリでは、該当する拡張子のファイルだけが選択されます。.js、.tsx、.pot、MJML、VTTのファイルは、CLIの入力ファイルとして設定されていません。React TSXの抽出は、これとは別の操作です。

HTML 翻訳では、選択したテキストと属性を元のソースに反映し、変更対象ではないマークアップ、コメント、書式はそのまま保持します。明示的な <html> 要素がある場合、その lang 属性にターゲットロケールを設定します。フラグメントはフラグメントのまま保持されます。テキストの選択と出力の動作については、HTMLを参照してください。

形式では、スキップされる構造や再構築の制限など、パーサーの動作を説明しています。共有サーバーハンドラーによって、この CLI の列挙値が拡張されることはありません。

出力パス #

ソースパスからロケールを識別できない場合は、テンプレートを明示的に指定してください。

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [
    {
      "pattern": "docs/**/*.md",
      "sourceRoot": "docs",
      "targetPath": "i18n/[locale]/docs/[path]"
    }
  ]
}

docs/start.md は i18n/de/docs/start.md と i18n/fr/docs/start.md になります。[locale] はエントリのロケール表現を使用し、[path] はセグメント境界に一致するソースルートを除去します。ルートが docs の場合、docsite の一部が除去されることはありません。

テンプレートには [locale] が必要です。グロブ入力には [path] も必要です。使用できるプレースホルダーはこの二つだけです。絶対パス、..、グロブを含むルート、入力の外側にあるルート、設定済みソースとして再検出される出力は拒否されます。targetPath のない sourceRoot は無効です。プッシュでは、大文字と小文字を区別せずに出力パスの衝突もチェックします。

プッシュ、プル、パージは、ファイルシステム上の参照先も確認します。ソース、ターゲット、.lingo/lock.json、.lingo/config.json の参照先が、シンボリックリンクなどによってプロジェクトルートの外側や .git 内になる場合、その場所で読み取り、書き込み、削除を行う前に、コマンドがエラーで停止します。参照先がプロジェクト内に収まるリンクは引き続き使用できますが、ターゲットや Lockfile 自体がリンクの場合、そのリンクを経由した書き込みは行いません。モノレポでは、パッケージから共有ファイルにリンクするのではなく、共有ファイルを含むルートから実行してください。

テンプレートがない場合は、ソースロケールのディレクトリ、拡張子を除いたファイル名全体、プラットフォームの配置規則の順に出力先の導出を試みます。いずれも使えない場合は、警告を表示してロケールディレクトリを挿入します。例として、locales/en.json → locales/de.json、app_en.arb → app_de.arb、Base.lproj → ターゲットの .lproj、アンドロイドの values → ロケール修飾付きリソースがあります。警告を確認し、アプリケーションがその出力先を読み込むことを確かめてください。

XCStrings と CSV はすべてのロケールをソースファイルに保存し、targetPath を拒否します。複数ロケールの出力が意図的に同じファイルを共有するため、ファイルが存在しても各ロケールが含まれているとは限りません。パージは共有ファイルをスキップするため、個別のロケールエントリは削除できません。

メタデータとコンポーネント内のテキストの選択 #

マークダウン系の翻訳では、オプションを省略するとフロントマターの title と description が選択されます。空のリストを指定すると選択を無効にでき、明示的なリストを指定すると他のフィールドを選択できます。入れ子のスカラーや配列のパスを指定するには、フロントマターが解析可能である必要があります。フロントマターの形式が不正な場合は、最上位の走査に切り替わることがあります。

json
{
  "pattern": "docs/en/**/*.mdx",
  "translateFrontmatterFields": ["title", "description"],
  "translateComponentProps": ["aria-label", { "component": ["Card", "Callout"], "props": ["title"] }]
}

文字列を指定すると、コンポーネントで絞り込まずにプロパティを選択します。オブジェクトを指定すると props を選択し、コンポーネント名で制限することもできます。これらのルールで選択されるのは、翻訳可能なリテラルの内容であり、コンポーネントのコードやすべての属性ではありません。マークダウン、MDX、Markdoc では動作が異なるため、パスを切り替える際はハンドラーを確認してください。

JSONC で翻訳者向けの指示を指定するには、対象の文字列の直前に @context を配置します。通常の JSONC 出力では @orphan マークは保持されますが、その他のコメントは削除されます。そのため、React の @src メタデータは、プルで保持されると想定せず、カタログ読み込みのポリシーに従って扱う必要があります。

ドキュメントフレームワークでは、ルーティングとは別に、実際のソースディレクトリと出力ディレクトリを選択してください。OpenAPI では yaml-openapi、Rails 形式のロケールルートでは yaml-root-key、汎用 YAML では yaml を使用します。拡張子の一致だけでは、適切な処理方式を選択できません。

ロケール #

設定では、網羅的なロケールの列挙値との照合ではなく、空でない文字列であることを検証します。地域や文字体系も含め、モデルとアプリケーションに必要な識別子を使用してください。localeFormat はパスを制御します。bcp47 はハイフンを保持し、underscore は pt_BR を生成し、android は pt-rBR や b+zh+Hans などの形式を生成します。アンドロイド形式では、上書きしない限りアンドロイド用の表記が選択されます。これはソースの照合にも影響します。

ターゲットを追加して不足ファイルを補完する前に、保留中の通常のソース更新を完了してください。言語の追加では、この順序で既存の言語を最新に保てる仕組みを説明しています。ターゲットを削除すると、既存ファイルは削除せず、今後の選択対象から除外します。埋め込みのロケールメタデータと共有カタログには、それぞれのハンドラーのルールが適用されます。パスが正しく記述されていても、文字の方向、ルーティング、言語品質が保証されるわけではありません。

カタログのパス #

抽出とチェックでは、明示的な --out/--types が最優先され、次に i18n の設定、最後に既定値が適用されます。--source-locale の既定値は en で、ローカライゼーションの sourceLocale とは独立しています。messagesPath を変更しても files[] は更新されません。翻訳対象には、生成された JSONC のパスを選択してください。

モノレポ #

ルート設定では、再帰的または明示的に指定したパッケージパス間で、ロケールとローカライゼーションエンジンを共有できます。一方、パッケージごとの設定を使えば、ロケール、設定、Lockfile をそれぞれ独立して管理できます。最も近い設定を探す際に、意図せず上位階層の設定が選択されないよう、目的のパッケージルートから実行してください。

CI のディレクトリマトリックスでは、各プロジェクトで収集した出力を保持し、書き込み処理の重複を避けてください。ホームディレクトリ内のローカルな実行ポインターは絶対ルートに依存しており、Lockfile では共有されません。lingo check は、files で選択したすべてのソースを Lockfile とファイル単位で比較します。ファイル内のキーはチェックしません。

スコアリング設定 #

lingo score は、Jiti 経由で読み込む実行可能な lingo.config.ts を使用します。これはプロジェクトの JSON とは別のもので、任意のローカル形式ローダーを登録するものではありません。信頼できるスコアリングプラグインと、リモートのファイルローカライゼーション設定は区別して管理してください。