GitHub App

Lingo.dev GitHub Appを使えば、.lingo/config.json によってリポジトリの継続的ローカライゼーションを設定できます。

前提条件#

アプリをインストールする前に、以下を確認してください。

• GitHub連携機能が有効なLingo.dev組織
• その組織内のローカライゼーションエンジン
• 接続したいGitHub組織またはリポジトリへの管理者権限

GitHub Appを接続する#

1. Lingo.devで組織を開きます。
2. Settings に移動します。
3. Integrationsセクションで GitHub (App) を探します。
4. GitHub (App) の行にある Connect をクリックします。
5. GitHubで、アプリをインストールするアカウントまたは組織を選択します。
6. All repositories または Only select repositories のいずれかを選択します。
7. Install をクリックします。

インストール後、Lingo.devの Settings > GitHub (App) に接続済みのGitHubアカウントとリポジトリが表示されます。あとからリポジトリを追加または削除したい場合は、同じ設定カードの Manage repositories on GitHub を使ってください。

インストールリクエストが承認待ちの場合、GitHub管理者はGitHubの組織内にある Settings > GitHub Apps で内容をレビューできます。保留中のアプリリクエストは、GitHubの組織設定で組織オーナーにも表示されます。

リポジトリ設定を追加する#

アプリをインストールしたリポジトリに .lingo/config.json を作成します。

{
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de"],
  "files": [
    { "pattern": "docs/en/**/*.md" },
    { "pattern": "docs/en/**/*.mdx" },
    { "pattern": "locales/en.json" }
  ],
  "github": {
    "workflows": {
      "onPushToDefaultBranch": { "enabled": true },
      "onPullRequest": { "enabled": true }
    },
    "safety": {
      "requireApproval": false
    }
  }
}

ファイルパターン#

files パターンはソース（デフォルトロケール）のファイルを指定します。アプリは変更されたファイルをこれらのパターンと照合し、一致したサポート対象のソースファイルだけを処理します。

パターンはリポジトリ相対で、大文字と小文字を区別し、以下を使用できます。

• 1つのパスセグメント内で一致させるには *
• 任意のディレクトリ深度に一致させるには **/

パターンは / で始めることはできず、.. を含めることもできません。

{
  "files": [
    { "pattern": "docs/en/**/*.md" },
    { "pattern": "src/content/en/**/*.mdx" },
    { "pattern": "messages/en.jsonc" }
  ]
}

ファイルオプション#

files の各エントリには、pattern に加えて追加オプションを指定できます。いずれも任意で、適用される形式はオプションごとに異なります。

translateComponentProps エントリには、任意のコンポーネントまたはタグのそのpropに適用されるprop名、またはpropsの適用先を特定のコンポーネントやタグに限定するオブジェクトを指定できます。

{
  "files": [
    {
      "pattern": "src/content/en/**/*.mdx",
      "translateFrontmatterFields": ["title", "description"],
      "translateComponentProps": [
        "alt",
        { "component": ["Callout", "Hero"], "props": ["title", "subtitle"] }
      ]
    },
    {
      "pattern": "locales/en.json",
      "lockedKeys": ["app.version"],
      "injectLocale": { "enabled": true, "key": "language" }
    }
  ]
}

ローカライズ済みファイルの出力先#

アプリは、ソースパスと設定内のロケールコードをもとに各ターゲットパスを決定します。

ロケールコードには、完全なディレクトリ名またはファイル名を使ってください。たとえば、ソースファイルが docs/en-US/ にある場合は、"sourceLocale": "en-US" を設定し、"en" は設定しません。ソース文字列が messages/en.json にある場合は、"sourceLocale": "en" を設定してください。

ソースパスにロケールディレクトリが含まれている場合、アプリはそのディレクトリを置き換えます。ソースパスがロケール名のファイルである場合は、ファイル名を置き換えます。どちらのパターンにも当てはまらない場合は、ソースファイルの隣に新しいターゲットロケール用ディレクトリを作成し、その中に翻訳済みファイルを配置します。

ワークフロー#

デフォルトブランチへのpush#

一致するソースファイルがデフォルトブランチに追加または変更されると、アプリが翻訳を実行し、ローカライズ済みファイルを次にコミットします。

lingo/translations/<default-branch>

続いて、アプリはそのtranslationsブランチからデフォルトブランチへのpull requestを作成または更新します。translationsブランチがすでに存在する場合は、そこに新しいコミットが追加されます。

同じpushでターゲットファイルが追加または変更されている場合、アプリはそのファイルをすでに処理済みとみなし、上書きせずに翻訳PRへ引き継ぎます。

Pull requests#

github.workflows.onPullRequest.enabled が true の場合、アプリはpull request内の変更を確認し、一致するソースファイルを探します。翻訳済みファイルはPRブランチに直接コミットされます。

アプリはforkされたPRブランチには書き込まず、PRコメントからデフォルトブランチへ書き込むこともありません。翻訳をコミットするには、pull requestがオープンである必要があります。

PRでは、Lingo.devが翻訳済みファイルと失敗内容を含むPRコメントを更新します。

差分更新と復旧#

既存のターゲットファイルについては、ファイル全体を再生成するのではなく、検出できたソースの変更部分だけを翻訳します。新しいターゲットファイルについては、設定された各ターゲットロケールごとにローカライズ済みファイルを作成します。

前回のPRローカライゼーションでソース変更の取りこぼしがあった場合や、ターゲットファイルの更新前に処理が失敗した場合でも、次回のPR同期でPRのソースとベースブランチのソースを比較し、不足している変更を翻訳することで復旧できることがあります。

処理対象のコミット時点でソースファイルが存在しない場合、アプリはそのファイルをスキップします。

承認モード#

自動翻訳を実行する前に人による承認ステップを入れたい場合は、github.safety.requireApproval を true に設定します。

デフォルトブランチへのpushでは、Lingo.devのcheck runに Approve と Deny のアクションが表示されます。pull requestでは、アプリが翻訳提案コメントを投稿するので、以下のいずれかで返信してください。

/lingo approve

スコープ付きの /lingo translate コマンドでは、この承認ゲートは不要です。

手動PRコマンド#

pull requestのコメントで /lingo を使うと、特定のファイルに対して翻訳を補完したり、翻訳を強制実行したりできます。

/lingo translate docs/en/**/*.md

/lingo translate docs/en/**/*.mdx --locales fr,es

/lingo translate docs/en/**/*.md --force

コマンドリファレンス：

コマンドは単独の行に記述する必要があります。globは、設定済みの files ソースパターンにも一致するファイルに対してマッチします。設定パターンと同様に、コマンドglobも / で始めることはできず、.. を含めることもできません。

デフォルトでは、/lingo translate はバックフィルモードで実行されます。つまり、PRブランチ上で不足しているターゲットファイルだけを作成します。既存のターゲットファイルを再生成したい場合は、--force を追加してください。

サポートされている形式#

GitHub Appは、ファイル拡張子から以下の形式を検出します。

• JSON（.json）
• JSONC（.jsonc）
• Markdown（.md）
• MDX（.mdx）
• Markdoc

YAMLで記述されたOpenAPIドキュメントにも対応していますが、自動では検出されません。ファイルパターンに "format": "yaml-openapi" を設定してください。

{
  "files": [
    { "pattern": "openapi/en.yaml", "format": "yaml-openapi" }
  ]
}

大規模な更新#

アプリは翻訳結果を複数のコミットに分割することがあります。これは、1回の実行で1コミットあたり100ファイルを超えて書き込む場合、または1コミットあたり5 MBを超える翻訳済みファイル内容を書き込む場合に発生します。

その場合、コミットメッセージには次のようにバッチ番号が含まれます。

feat: Lingo.dev translations (1/3)
feat: Lingo.dev translations (2/3)
feat: Lingo.dev translations (3/3)

一致するものがない場合の動作#

.lingo/config.json がない場合、アプリはそのリポジトリを何もせずスキップします。設定ファイルが存在する場合は、無効な設定によって失敗するcheck runが作成され、PRでは検証エラーを含むコメントも投稿されます。

変更されたファイルがソースパターンに1つも一致しない場合、アプリは翻訳を書き込まずに完了します。/lingo translate では、一致するファイルがない、一致するロケールがない、またはすべてのターゲットファイルがすでに存在するといった簡単な説明をボットが返信します。

次のステップ#