GitHub
GitHub Appでリポジトリのコンテンツを翻訳。ソースの変更も翻訳結果も、レビューできる形で管理できます。
Lingo.dev GitHub Appを使うと、翻訳ファイルもリポジトリの変更履歴に記録できます。ソースコンテンツと翻訳設定をコミットすると、アプリが対象ファイルを読み込み、ローカライゼーションエンジンで翻訳して、チームがGitHubで確認できる差分を返します。
Studio 2.5のナビゲーションでは、設定 → 連携ではなく、Studio 2.5 → 連携を開いてください。既存の接続用リンクとセットアップ用リンクは、引き続きご利用いただけます。
既定ブランチに変更があると、翻訳のプルリクエストが作成されます。プルリクエストの処理を有効にした場合は、そのプルリクエストのブランチに翻訳が追加されます。このページでは既定ブランチのワークフローから説明し、翻訳の反映とマージの判断を分けて扱います。独自のランナーでCLIを実行する場合は、GitHub Actionsのレシピを参照してください。
コーディングエージェントをアプリに接続する方法は、コーディングエージェントでセットアップするをご覧ください。
リポジトリを接続し、翻訳を設定する #
Lingo.devで設定 → 連携を開き、GitHubの接続を選択します。インストールしたアプリを組織に接続し、処理対象のリポジトリへのアクセスを許可してください。インストールには、GitHubの組織管理者による承認が必要な場合があります。アクセスできるリポジトリは、インストール時に選択した範囲に限られます。
接続先の組織で、利用可能なローカライゼーションエンジンを選択します。使用するモデル、用語集、ルール、語り口、適用されるレビューの動作は、このエンジンの設定に従います。GitHubのインストール権限はリポジトリでの操作を許可し、Lingo.devの権限はローカライゼーションエンジンの利用を許可します。
設定 → 連携で接続を開くと、インストールの状態と接続が正常かどうかを確認できます。GitHubで管理を選択すると、インストールしたアプリのリポジトリアクセス設定が開きます。Studioの接続済みからリポジトリを選び、ワークフロー実行とGitHubのチェック、コミットを併せて確認すると、特定のソース変更を追跡できます。
組織でStudio 2.5が有効になっている場合、ソースコンテンツサイドバーには、接続したアプリからアクセスできるリポジトリが、GitHubのイベントを待たずに表示されます。既定ブランチに有効な.lingo/config.jsonがあれば、新たなコミットや翻訳の実行なしで、設定済みのJSON・JSONCソースファイルと既存の翻訳を開けます。閲覧しても翻訳クレジットは消費されず、自動同期が有効になることもありません。有効な設定がないリポジトリも表示されますが、ファイルを開くと設定エラーが表示されます。
リポジトリのルートに.lingo/config.jsonを作成します。この例では、locales/en/内にある英語のJSONカタログを選択し、対応するlocales/fr/のパスにフランス語のファイルを生成します。eng_exampleを、使用するローカライゼーションエンジンのIDに置き換えてください。
{
"engineId": "eng_example",
"sourceLocale": "en",
"targetLocales": ["fr"],
"files": [
{
"pattern": "locales/en/**/*.json",
"format": "json"
}
],
"github": {
"workflows": {
"onPushToDefaultBranch": { "enabled": true },
"onPullRequest": { "enabled": false }
},
"safety": { "requireApproval": true }
}
}一度実行し、結果を確認する #
この例では、翻訳の開始前に承認が必要です。次の手順でテストしてください。
- 設定とソースの小さな変更を既定ブランチにコミットします。たとえば、
locales/en/checkout.json内のメッセージを一つ変更します。 - 保留中のGitHubチェックを開き、実行を承認します。承認できない場合は、承認ルールを確認してください。
- アプリが作成または更新した翻訳のプルリクエストを開きます。
locales/fr/checkout.jsonを見つけ、変更されたメッセージをソースと比較します。 - 翻訳ファイルを使ってアプリケーションをビルドまたは実行します。文言、変数、ロケールの選択を確認したら、リポジトリでの通常の手順に従ってプルリクエストをレビューし、マージします。
手順2の承認は、翻訳作業とそれに伴う使用量を許可するものです。翻訳結果の文言の承認や、プルリクエストのマージではありません。出力が見つからない場合は、確認と復旧を参照して、どの段階が未完了かを特定してください。
ファイル構成に合わせて設定を調整する #
ソースパターンでは、ソースファイルだけを選択してください。たとえば、locales/en/**/*.jsonを使うと、生成されたフランス語ファイルが後からソースとして検出されるのを防げます。パターンはリポジトリからの相対指定です。絶対パスと..は使用できません。各ファイルエントリには、patternまたはincludeのリストが必要です。一つの設定に、最大100件のファイルエントリと50種類の翻訳先ロケールを指定できます。
既定では、パスに含まれるソースロケールによって翻訳先ファイルの出力先が決まります。パスにロケールが含まれない場合は、targetPathを設定してください。[locale]には翻訳先ロケールが入り、[path]には省略可能なsourceRootプレフィックスを取り除いたソースパスが入ります。たとえば、sourceRoot: "content"とtargetPath: "translations/[locale]/[path]"を使うと、フランス語ではcontent/help/start.mdがtranslations/fr/help/start.mdに対応します。グロブを使うテンプレートには、両方のプレースホルダーが必要です。sourceRootにはtargetPathが必要で、選択したソースのパスの先頭と一致している必要があります。Xcodeの文字列カタログやCSVのように、一つのファイルで複数のロケールを扱う形式では、翻訳が元のファイル内に保存されるため、出力テンプレートは使用できません。
アプリケーションのパスで、BCP-47、アンダースコア区切り、またはAndroid形式のロケール表記が必要な場合は、localeFormatを使います。Androidリソースには、既定でAndroidの修飾子が使われます。ロケールを追加する前に、最初の出力パスがアプリケーションのローダーに適合していることを確認してください。
翻訳の実行タイミングと書き込み先を選ぶ #
既定ブランチへのプッシュ処理は、既定で有効です。プルリクエストの処理は既定で無効のため、設定で明示的に有効にする必要があります。
プルリクエストの処理を有効にする前に、有効な.lingo/config.jsonを既定ブランチにコミットしてください。アプリは、信頼できる既定ブランチのリビジョンから、エンジンID、github.workflows、github.safetyを読み取ります。プルリクエストでこれらの設定を変更しても、そのプルリクエスト自身の実行で別のエンジンの使用を許可したり、承認ポリシーを変更したりすることはできません。ソースロケール、対象ファイル、翻訳先ロケールは、翻訳対象のリビジョンから取得されます。
| トリガー | 翻訳の反映先 |
|---|---|
| 既定ブランチへのプッシュ | lingo/translations/<default-branch>にコミットし、既定ブランチへのプルリクエストを作成または更新します。 |
| 有効化されたプルリクエストのワークフロー | 翻訳結果をプルリクエストのヘッドブランチにコミットします。 |
| プルリクエスト上の翻訳コマンド | 要求された翻訳結果を、そのプルリクエストのヘッドブランチに書き込みます。 |
プルリクエストへの反映には、アプリのインストール先リポジトリに、書き込み可能なヘッドブランチが必要です。アプリはフォークをスキップし、この出力を既定ブランチに直接書き込むことはありません。
アプリはリポジトリでの作業を順番に処理し、自身が生成したコミットを除外することで、翻訳が繰り返し起動するのを防ぎます。設定済みのソースに変更がない場合や、要求された作業が翻訳先にすでに反映されている場合は、差分なしで実行が完了することがあります。結果はチェックで確認できます。強制再生成は、選択した翻訳を置き換えるための機能です。変更のない実行を、処理が行われたように見せるためのものではありません。
実行で費用が発生する前に承認を必須にする #
github.safety.requireApprovalの既定値はfalseです。翻訳の開始前に承認を必須にする場合は、既定ブランチの設定でtrueにしてください。既定ブランチへのプッシュでは、チェックに承認と拒否の操作が表示されます。プルリクエストでは、アプリがコメントを投稿し、権限のあるレビュー担当者が/lingo approveで応答します。
承認が必要な場合、監査用チェックを作成できないとワークフローは先に進みません。チェックの作成やアクセスの問題を解決してから、再度承認を試みてください。
/lingo translateコマンドは、ファイルのグロブ指定の有無にかかわらず、要求した作業の実行を許可し、この事前承認を省略します。投稿する前に、対象のファイルとロケールの範囲を確認してください。
プルリクエストでコマンドを実行する #
アプリのインストール先リポジトリに属し、既定ブランチではないブランチの、開いているプルリクエストにコメントします。アプリは、コメント内で/lingoから始まる最初の行を読み取ります。ソースロケール、ファイルオプション、翻訳先ロケールにはプルリクエストのヘッドの設定を使い、エンジンと安全性に関する設定には既定ブランチの設定を使います。翻訳を開始できるのは、リポジトリへの書き込み権限を持つ人だけです。
| コマンド | 動作 |
|---|---|
/lingoまたは/lingo help | コマンドの一覧を返信します。 |
/lingo translate | このプルリクエストのソース変更を翻訳し、変更のない翻訳は保持します。前回のプッシュから保留中の翻訳案がある場合は、その案を置き換えます。 |
/lingo translate --locales fr,es | このプルリクエストのソース変更を、指定したロケールにのみ翻訳します。 |
/lingo translate <glob>... | 設定済みのソースのうち、グロブに一致するものについて、不足している翻訳先ファイルを作成します。 |
/lingo translate <glob>... --force | 一致する翻訳先を再生成し、既存の翻訳を置き換えます。--forceには少なくとも一つのグロブが必要です。 |
/lingo translate [<glob>...] --key <pattern> | 既存の翻訳で、指定に一致する名前付きキーを再翻訳します。 |
/lingo approve | このプルリクエストで保留中の翻訳案を承認します。 |
グロブも--keyも指定しない場合、コマンドはプルリクエストで変更されたファイルを対象とします。そのため、設定でプルリクエストの処理が無効になっていても実行されます。グロブを指定した場合は、プルリクエストの変更内容に関係なく、ブランチ上のファイルを対象とします。グロブはリポジトリのルートからの相対指定で、大文字と小文字を区別します。対象になるのは、設定済みのpatternが選択するファイルだけです。--localesにはカンマ区切りのリストを指定します。コードは大文字と小文字を区別せず、設定済みの翻訳先ロケールと照合されます。どのロケールにも一致しないコードは、返信に記載されます。
グロブとキーの指定方法については、選択したファイルやロケールの不足分を補うとコンテキストを指定してキーを再翻訳するで詳しく説明しています。
選択したファイルやロケールの不足分を補う #
プルリクエストに対象範囲を絞ったコマンドを投稿し、設定済みのファイルとロケールを一つずつ指定して翻訳を要求します。
/lingo translate locales/en/checkout.json --locales frロケールごとにファイルを分ける形式では、不足しているフランス語の翻訳先ファイルが作成されます。既存の翻訳先ファイル内で不足しているキーは補完されません。--forceを追加すると、既存の翻訳先を再利用せずに、選択した出力を再生成します。そのため、人が編集して承認された内容も置き換えられる可能性があります。対象のファイルとロケールを絞り、生成された差分をレビューしてください。
Xcodeの文字列カタログとCSVファイルでは、原文と翻訳を一つのファイルに保存します。範囲を指定して通常のコマンドを実行すると、不足しているロケールのエントリーが補われ、原文が変更されたものも含め、既存のエントリーはそのまま保持されます。プルリクエストで変更された原文を翻訳するには、ファイルパターンを指定せずに/lingo translateを使用してください。この操作では、変更対象のエントリーにある既存の翻訳が、手動での編集内容も含めて置き換えられる場合があります。既存の翻訳を再生成する場合は、対象のファイルとロケールを絞り込んだうえで--forceを追加してください。アプリのコマンドを強制実行すると、選択したコンテンツが再構築されます。その際も、指定範囲外のロケールは保持されます。CLIで更新する場合は、文字列カタログまたはCSVの修正手順に従ってください。
コンテキストを指定してキーを再翻訳する #
--keyを使うと、既存の翻訳から選択した名前付きキーを再翻訳できます。JSON・JSONCファイルでは、--contextを追加してキーの意味を説明したり、その実行でのトーンや大文字・小文字の使い方を指示したりできます。
/lingo translate --key "keyname" --context "button label, keep sentence case"--contextには--keyが必要です。コンテキストは一度だけ指定し、JSON・JSONCファイル内で選択されたすべてのキーとロケールに適用します。一致する他の形式は、このコンテキストなしで翻訳されます。複数のパターンを指定するには--keyを繰り返し、ファイルのグロブまたは--localesで対象範囲を絞ってください。ファイルのグロブを指定しない場合、コマンドは設定済みのすべてのソースファイルを選択します。キーは完全一致、接頭辞、またはグロブで照合され、無関係な翻訳は保持されます。名前付きキーのない形式と、既存の翻訳がないロケールはスキップされます。
GitHub Appのキー指定コマンドは、YAMLとロケールルート形式のYAMLでも、選択した文字列を変更の有無にかかわらず再生成します。これらの形式では、CLIのキー指定ワークフローとは、既存の翻訳を再利用する基本動作が異なります。
コマンドは一行に収めてください。空白を含むコンテキストは、一重引用符または二重引用符で囲みます。--context="button label"も使用できます。テキスト内に囲みと同じ引用符を含める場合は、--context "Use \"Save\" as a button label"のようにバックスラッシュでエスケープしてください。コンテキストは再試行や履歴のために実行とともに保持されますが、エンジンへの指示として保存されたり、後続の実行に引き継がれたりすることはありません。既存の用語集、プレースホルダー、出力形式のルールは引き続き適用されます。
引用符で囲んだコンテキスト内では、\\と、囲みに使った引用符の直前にあるバックスラッシュだけがデコードされます。$nameや${name}などのプレースホルダー、\nなどの文字列、句読点は、記述どおりに保持されます。
変更しないコンテンツを保護する #
このアプリは、構造化カタログ、マークダウン系ドキュメント、HTML、字幕、プレーンテキスト、CSVテーブル、Javaプロパティファイル、プラットフォームリソースに対応しています。各形式のハンドラーについては、形式をご覧ください。Payloadは、GitHubのファイル形式としては選択できません。
HTMLを選択するには、pages/en/**/*.htmlやpages/en/**/*.htmなどのパターンを使います。どちらの拡張子もhtmlと推定され、"format": "html"を明示的に指定することもできます。HTML出力では、翻訳したテキストと選択した属性をソースに反映し、変更対象外のマークアップ、コメント、書式は保持します。<html>要素が明示されている場合は、そのlangに翻訳先ロケールが設定されます。断片にドキュメント全体を囲む要素が追加されることはありません。
プレーンテキストファイルを選択するには、metadata/en/*.txtのように.txtで終わるパターン、または"format": "txt"を使用します。.txtファイルはこうしたエントリでのみ選択され、"format": "txt"を指定したエントリでは.txtファイルのみが選択されます。そのため、docs/en/**/*のように広範囲を対象とするパターンでもLICENSE.txtは除外され、広範囲を対象とするtxtのエントリでも、テキストと同じ場所にある画像は除外されます。プレーンテキストでは、各行を元の位置のまま翻訳します。
CSVファイルも同じ方法で選択できます。i18n/strings.csvのように.csvで終わるパターンを指定するか、"format": "csv"を使用してください。.csvファイルを扱えるのは、このようなエントリーのみです。また、"format": "csv"を指定したエントリーでは、.csvファイルのみが選択されます。CSVでは、ソースファイル内の翻訳先ロケールの列に翻訳が入力されます。
Javaプロパティファイルも同様に、src/main/resources/messages_en.propertiesのように.propertiesで終わるパターンで選択するか、"format": "properties"を指定して、src/main/resources/**/*のような広範囲に一致するパターンでもapplication.propertiesが除外されるようにします。messages_en.propertiesという名前のソースには、messages_de.propertiesなどのターゲットが作成されます。Javaプロパティでは、コメントとレイアウトを保ちながら各値を元の位置で翻訳し、従来のCLIと同様にlockedKeys、preservedKeys、ignoredKeys、lockedPatternsを照合します。
ドキュメントでは、翻訳対象のテキストを含むフロントマターのフィールドとコンポーネントのプロパティを選択します。JSON系のカタログでは、ロック対象のパスでソースの値をコピーし、保持対象のパスで既存の翻訳先の値を残し、無視対象のパスで値を出力から除外します。これにより、テキストと識別子、リンクが同じカタログ内にあっても、翻訳時にそれぞれを適切に扱えます。ロケール挿入では、設定した出力フィールドに翻訳先ロケールを書き込みます。
ファイルエントリのオプション #
次のフィールドは、.lingo/config.jsonのfiles配列内のオブジェクトに直接配置してください。optionsの下には配置しません。アプリは、ルートフィールド、ファイルエントリ、GitHub設定、コンポーネントルール、ロケール挿入オブジェクトを厳密に検証します。任意のi18nセクションは無視され、このセクション内では追加フィールドも許可されます。機械可読スキーマはGET https://api.lingo.dev/github-app/schema.jsonで参照できます。
| フィールド | 指定できる形式 | 既定値または適用範囲 |
|---|---|---|
pattern / include | リポジトリからの相対パスを表す空でない文字列、またはその文字列からなる空でない配列。 | 少なくとも一方が必須。includeを指定するとpatternより優先されます。パターンは/で始めたり、..を含めたりできません。 |
exclude | リポジトリからの相対指定による、空でないパターンの配列。 | 任意。このエントリに適用されます。 |
format | "html"を含む、設定で使用できる形式文字列。 | 任意。省略時は推定されます。.htmlと.htmはHTMLを選択します。Payloadは選択できません。ドキュメントの{type,options}オブジェクトとは異なります。 |
localeFormat | "bcp47"、"underscore"、または"android"。 | 通常の既定値はBCP-47。Android形式ではAndroid表記が使われます。 |
targetPath、sourceRoot | リポジトリからの相対パスを表す空でない文字列。 | 任意。上記の出力テンプレートのルールに従ってください。 |
lockedKeys、preservedKeys、ignoredKeys | ドットまたは角括弧で指定する、空でないキーパス文字列の配列。 | 省略時は[]。動作は形式ごとの処理に依存します。ドキュメントのJSONPathオプションをそのまま指定するものではありません。 |
injectLocale | 真偽値または{ "enabled": boolean, "key"?: nonempty string }。 | 省略時は挿入が無効。有効な場合、keyがなければ既定でlanguageになります。 |
translateFrontmatterFields | 空でない文字列の配列。 | マークダウン系ドキュメントでは、省略時にtitleとdescriptionを選択。[]を指定すると何も選択しません。 |
translateComponentProps | 空でないプロパティ名の文字列、または任意のcomponentと必須の空でないprops配列を持つオブジェクトの配列。 | componentは空でない文字列、または空でない文字列からなる空でない配列。省略すると名前で絞り込まなくなります。このフィールドの既定値は[]です。 |
たとえば、JSONエントリには"lockedKeys": ["meta.id"], "preservedKeys": ["links.help"], "injectLocale": { "enabled": true, "key": "meta.locale" }をpatternと併せて指定できます。マークドックのエントリでは、"translateComponentProps": [{ "component": "Callout", "props": ["title"] }]でコンポーネントのタイトルを選択できます。CLIでは一部の空の値が許可され、一部の不明なフィールドは警告のみで処理されますが、アプリでは拒否されます。アプリの設定は、このスキーマに照らして検証してください。
最初の継続実行を確認し、問題があれば復旧する #
GitHubのチェックとワークフロー実行で、リポジトリ、ソースリビジョン、ローカライゼーションエンジン、対象ファイル、ロケール、反映先ブランチを確認します。想定していた変更と照らし合わせ、どこで処理が止まったかを特定してください。
| 状況 | 追加の処理を要求する前に確認すること |
|---|---|
| 既定ブランチの設定がない、設定が無効、または設定でワークフローが無効になっている | GitHubのチェックもコメントも投稿されません。既定ブランチの.lingo/config.jsonを、意図したワークフロー設定を含めて修正し、コミットしてください。 |
| 既定ブランチのチェックは通過したが、ソースリビジョンの設定がない、または無効になっている | チェックで実行の失敗が報告され、該当するプルリクエストのフローではコメントも投稿されます。報告されたソース設定のエラーを修正してください。 |
| 一致するソース変更がない、または対象範囲がすでに翻訳済み | パターンと選択された対象範囲を確認してください。処理対象がないことは、翻訳の失敗ではありません。 |
| プルリクエストのソース変更が以前の処理で見逃されている | プルリクエストの同期時には、そのベースとの比較により、直前のソースとの比較で見逃した処理を補える場合があります。ベースと現在のソース、翻訳先を併せて確認してください。 |
| 人がプルリクエストの翻訳先を編集した | 翻訳先が別ファイルの形式では、通常のプルリクエストの差分処理は、ベースから変更され、最新コミットの作成者がボットではない翻訳先を保護します。出力がスキップされても未処理とはみなさず、その編集内容を確認してください。 |
| 処理の途中で失敗したが、それ以前に一部のコミットが作成されている | 出力は複数のバッチに分けてコミットされる場合があります。一回の実行に複数のコミットが含まれることがあり、後続のバッチが失敗しても、先に成功したコミットは元に戻りません。反映済みのパスと、残っている失敗を分けてレビューしてください。 |
出力は、100ファイルの上限と5メビバイトのしきい値に基づいてまとめられ、コミットされます。後続の処理が失敗しても、それ以前のコミットは残る場合があります。実行を再試行したり元に戻したりする前に、反映済みのパスと残っている失敗をレビューしてください。
繰り返しの処理を停止するには、該当するトリガーを無効にします。アプリにリポジトリの操作権限を与える必要がなくなったら、GitHubでリポジトリへのアクセスを取り消すか、アプリをアンインストールしてください。既存のコミット、受け入れ済みのプルリクエスト、過去の使用量は残ります。反映済みのコンテンツを保持する場合も元に戻す場合も、リポジトリでの通常の手順に従ってください。
Radarにアクティビティを収集する #
この接続は、GitHubのコミットアクティビティをRadarにも提供します。測定用に翻訳を収集するでは、イベントの設定と、過去のデータを測定する前にプロバイダーの履歴をインポートする方法を説明しています。