GitHub App

Moses Skodaエンジニア読了目安 4分

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

コーディングエージェントからアプリに接続するには、コーディングエージェントを使ったセットアップをご覧ください。

前提条件#

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

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

GitHub組織の管理者でない場合は、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 では、保留中のアプリリクエストが組織設定内で組織オーナーにも表示されます。

組織でStudio 2.5が有効になっている場合、ソースコンテンツサイドバーには、接続済みのインストールからアクセスできるリポジトリが、GitHubのイベントを待たずに一覧表示されます。デフォルトブランチに有効な.lingo/config.jsonがあれば、新たにコミットしたり翻訳を実行したりすることなく、設定済みのJSON・JSONCソースファイルと既存の翻訳を開けます。閲覧しても翻訳クレジットは消費されず、自動同期が有効になることもありません。有効な設定がないリポジトリも引き続き表示されますが、そのファイルを開くと設定エラーが表示されます。

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

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

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
    }
  }
}
項目必須説明
engineIdはいこのリポジトリを翻訳するLingo.devエンジン。
sourceLocaleはいen や en-US など、ソースファイルのパスで使われるソースロケール。
targetLocalesはい翻訳先のロケールコード。最大50個の重複しないロケールをサポートします。
filesはいリポジトリ相対のソースファイルパターン。最大100個のパターンを指定できます。
github.workflows.onPushToDefaultBranch.enabledいいえデフォルトブランチでソースファイルが変更されたときに実行されます。デフォルトで有効です。
github.workflows.onPullRequest.enabledいいえpull requestでソースファイルが変更されたときに実行されます。デフォルトでは無効です。
github.safety.requireApprovalいいえ自動pushまたはPRワークフローで翻訳を実行する前に、承認を必須にします。デフォルトでは無効です。

CLIを使ってリポジトリの設定を書き込みます。次のコマンドを順番に実行してください。

  1. npx @lingo.dev/cli initを実行して、ソースロケール、ターゲットロケール、ファイルパターンを.lingo/config.jsonに書き込みます。
  2. npx @lingo.dev/cli loginを実行してサインインし、認証情報をローカルの~/.lingo/credentials.jsonに保存します。
  3. npx @lingo.dev/cli linkを実行して、組織とエンジンを選択します。これにより、.lingo/config.jsonにorgIdとengineIdが追加されます。

initコマンドでは、githubセクションは書き込まれません。このセクションが必要な場合は、上の例からコピーしてください。詳しくは、CLIクイックスタートをご覧ください。

ファイルパターン#

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

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

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

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

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

ファイルオプション#

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

オプション適用先説明
formatすべてファイル拡張子から推定された形式を上書きします。OpenAPI YAML("yaml-openapi")では必須です。
include / excludeすべてこのエントリが一致するファイルをさらに絞り込むためのglobリストです。pattern と併用することも、代わりに使うこともできます。
translateFrontmatterFieldsMarkdown、MDX、Markdoc翻訳対象にするfrontmatterキー。デフォルトは title と description です。
translateComponentPropsMDX、Markdoc翻訳対象にするMDXコンポーネントのpropsとMarkdocタグの属性。
lockedKeysJSON、JSONCソース値のまま保持され、翻訳されないキーパス。
preservedKeysJSON、JSONC既存のターゲット値のまま保持され、再翻訳しないキーパス。
injectLocaleJSON、JSONC指定したキーにターゲットロケールコードを出力します(デフォルトは language)。

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

json
{
  "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/guide.mdesdocs/es/guide.md
docs/en-US/guide.mdfr-FRdocs/fr-FR/guide.md
locales/en.jsondelocales/de.json
README.mdeses/README.md
Localizable.xcstringses-MXLocalizable.xcstrings(同じファイル)

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

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

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

ワークフロー#

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

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

txt
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では、アプリが翻訳提案コメントを投稿するので、以下のいずれかで返信してください。

txt
/lingo approve

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

手動PRコマンド#

プルリクエストのコメントで/lingoを使うと、ソースの変更箇所の翻訳、不足しているターゲットファイルの補完、選択したキーの再翻訳ができます。

変更のない翻訳を保持したまま、プルリクエスト内のソースの変更箇所を翻訳します。

txt
/lingo translate

不足しているターゲットファイルを補完するには、ファイルのグロブパターンを指定します。

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

コマンドリファレンス:

コマンド説明
/lingoヘルプを表示します。
/lingo helpヘルプを表示します。
/lingo translate変更のない翻訳を保持したまま、このプルリクエスト内のソースの変更箇所を翻訳します。
/lingo translate --locales fr,esこのプルリクエスト内のソースの変更箇所を、設定済みのターゲットロケールから選択したロケールに翻訳します。
/lingo translate <glob>...一致するソースファイルに対して、不足しているターゲットファイルを翻訳します。
/lingo translate <glob>... --locales fr,es実行対象を設定済みのターゲットロケールに限定します。ロケール値はコマンドパーサーによって小文字化されます。
/lingo translate <glob>... --force対象範囲内の一致するすべてのソースとロケールを翻訳し、既存のターゲットを上書きします。
/lingo translate [<glob>...] --key <pattern>既存の翻訳で、パターンに一致する名前付きキーを再翻訳し、それ以外の翻訳は保持します。複数のパターンを指定するには、--keyを繰り返し指定します。
/lingo translate [<glob>...] --key <pattern> --context "text"今回の実行で選択したすべてのキーとロケールに、この実行に限って適用する指示を追加します。--keyが必要です。--contextは一度だけ指定します。
/lingo approvePR上で保留中の翻訳提案を承認します。

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

ファイルのグロブパターンを明示的に指定し、--keyを省略すると、/lingo translate <glob>...は補完モードで動作します。このモードでは、プルリクエストのブランチに存在しないターゲットファイルだけを作成します。既存のターゲットファイルも再生成するには、--forceを追加します。

選択したキーを再翻訳する#

--keyを使うと、選択した名前付きキーだけを更新できます。他のキーに対する承認済みの編集も含め、対象外の翻訳は置き換えません。

txt
/lingo translate locales/en.json --key "auth.login" --locales fr,es

キーパターンには、完全一致、プレフィックス、グロブを使用できます。

パターン選択対象
auth.login名前付きキーauth.loginと、そのプレフィックス配下にあるすべての子孫キーに一致します。
authauthと、auth.loginやauth.logoutなどの子孫キーに一致します。
auth.*グロブパターンで、auth.loginやauth.logoutなどのキーに一致します。

複数のパターンを選択するには、--keyを繰り返し指定します。スペースを含むキーパターンは引用符で囲んでください。ファイルのグロブパターンと--localesで対象を絞り込めます。ファイルのグロブパターンを省略すると、設定済みのすべてのソースファイルが選択されます。

txt
/lingo translate --key "auth.*" --key "checkout.submit" --locales fr

キーを指定して翻訳するには、名前付きキーに対応した形式と、選択した各ターゲットロケールの既存の翻訳が必要です。名前付きキーのない形式や、既存の翻訳がないロケールはスキップされます。不足しているターゲットを先に作成するには、--keyを指定せずに/lingo translate <glob>...を実行します。キーを指定したコマンドに--forceを追加しても、対象キーの範囲は広がらず、対象外の翻訳も置き換えられません。

実行ごとにコンテキストを指定する#

--contextを追加すると、選択したキーの意味や、トーン、大文字・小文字の使い分けに関する指示を伝えられます。

txt
/lingo translate --key "keyname" --context "button label, keep sentence case"

--contextには--keyが必要です。コンテキストは一度だけ指定します。その実行で選択したすべてのキーとロケールに適用されます。再試行や履歴のために実行とともに保持されますが、保存済みのエンジンのルールや指示は変更せず、以降の実行にも引き継がれません。既存の用語集、プレースホルダー、出力形式に関するルールは引き続き適用されます。

コマンドは一行で記述してください。スペースを含むコンテキストは、一重引用符または二重引用符で囲みます。--context="button label"も使用できます。囲みに使った引用符をテキスト内に含めるには、バックスラッシュでエスケープします。

txt
/lingo translate --key "checkout.submit" --context "Use \"Save\" as a button label"

引用符で囲んだコンテキスト内では、\\と、囲みに使った引用符の直前にあるバックスラッシュだけがエスケープとして解釈されます。$nameや${name}などのプレースホルダー、\nなどの文字列、句読点はそのまま保持されます。

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

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

  • JSON(.json)
  • JSONC(.jsonc)
  • Markdown(.md)
  • MDX(.mdx)
  • Markdoc
  • Xcode String Catalog(.xcstrings)

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

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

Xcode String Catalog#

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

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

大規模な更新#

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

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

txt
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 では、一致するファイルがない、一致するロケールがない、またはすべてのターゲットファイルがすでに存在するといった簡単な説明をボットが返信します。

.lingo/config.jsonを追加するプッシュでは、ファイルパターンに一致し、かつそのプッシュで変更されたソースファイルのみが翻訳されます。変更のない既存のソースファイルは、別途補完する必要があります。これらに対応する未作成のターゲットファイルを作成するには、フォークではなく、同じリポジトリ内のブランチからプルリクエストを作成してください。そのプルリクエストに/lingo translate <glob>とコメントしてください。

次のステップ#