GitHub App

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

前提条件#

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

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

GitHub Appをインストール#

1. Lingo.devで組織を開きます。
2. Studio > All integrations に移動します。
3. GitHub カードで Install on GitHub をクリックします。
4. GitHubで、アプリをインストールするアカウントまたは組織を選択します。
5. All repositories または Only select repositories のいずれかを選択します。
6. Install をクリックします。

GitHub から Lingo.dev に戻ると、Connect GitHub 画面が表示されます。

1. この GitHub アカウントでローカライズに使用する Lingo.dev 組織を選択します。最後に開いた組織があらかじめ選択されています。
2. Connect をクリックします。
3. GitHub connected と表示されたら、View integration をクリックして接続を開きます。

接続は Studio のサイドバーにある Connected の下に表示されます。Settings タブでは、Account、Account type、Installation、Repositories、Connection が正常に動作しているかどうかを確認できます。Workflow runs タブには、アプリによるすべての実行履歴が表示され、各実行についてリポジトリ名と、プッシュまたはプルリクエストのどちらが開始のきっかけになったかが示されます。

あとからリポジトリを追加または削除するには、接続の Settings タブを開き、Manage on GitHub を使います。リポジトリアクセスは常に GitHub 側で、インストール自体に対して選択します。

インストールせずにインストールをリクエストした場合、Lingo.dev には Installation requested と表示されます。承認には GitHub 組織の管理者が必要です。承認されると、完了のために GitHub から Connect 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" を設定してください。

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

String Catalog は例外です。1つの.xcstringsファイルにすべてのロケールが含まれるため、ターゲットパスはソースパスと同じになります。アプリは各ロケールをその同じファイルに書き込み、ロケール用のディレクトリやファイル名を追加することはありません。

ワークフロー#

デフォルトブランチへの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
• Xcode String Catalog（.xcstrings）

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

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

Xcode String Catalog#

Xcode String Catalog では、すべてのロケールを1つの.xcstringsファイルで管理するため、ロケールごとにファイルを作成するのではなく、そのファイルに直接翻訳を書き込みます。ターゲットパスはソースパスと同じです。各ターゲットロケールは、ソース言語やすでに翻訳済みのロケールと並んで、同じファイルに書き込まれます。ソースパターンをカタログに直接指定し、sourceLocaleをその開発言語に設定してください。

{
  "sourceLocale": "en",
  "targetLocales": ["es-MX", "fr-CA", "pt-BR"],
  "files": [{ "pattern": "**/*.xcstrings" }]
}

大規模な更新#

アプリは翻訳結果を複数のコミットに分割することがあります。これは、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 では、一致するファイルがない、一致するロケールがない、またはすべてのターゲットファイルがすでに存在するといった簡単な説明をボットが返信します。

次のステップ#