Lingo check
翻訳が最新でなければ CI を失敗させ、React カタログもチェックします。
lingo check は、翻訳が最新でなければ失敗します。各ソースファイルを .lingo/lock.json と比較し、すべての翻訳先ファイルが存在することを確認します。@lingo.dev/react プロジェクトでは、抽出されたカタログ、宣言、コンテキスト、翻訳もチェックします。
lingo check --jsonどのチェックが実行されるか #
| チェック | 実行条件 |
|---|---|
| ファイルチェック | .lingo/config.json に files がある、または React プロジェクトではない場合。 |
| React チェック | ルートの package.json、または --src に最も近いものに @lingo.dev/react、@lingo.dev/react-next、@lingo.dev/react-tanstack のいずれかが記載されているか、生成された宣言ファイル(既定では lingo.d.ts)が存在する場合。 |
files がある React プロジェクトでは、両方のチェックが実行されます。どの files パターンにもファイルが一致しない場合は、lingo push と同様に no-source-files でチェックが失敗します。ただし、React プロジェクトでは React チェックのみが実行され、その旨が標準エラー出力に表示されます。files も React もないプロジェクトでは、lingo push と同じ設定エラーで失敗します。
lingo check に API キーは不要で、書き込みも行いません。DO_NOT_TRACK=1 で無効になる CLI テレメトリを除き、ネットワーク通信も行いません。問題を報告した場合や設定エラー(翻訳先の競合や Lockfile の破損など)が発生した場合は終了コード 1、それ以外は 0 で終了します。
ファイルチェック #
ソースは、lingo push が送信対象とするファイルです。翻訳先は、設定された各翻訳先ロケールについて、プッシュ時に書き込み先となるパスです。
| 状況 | 問題 | 修正方法 |
|---|---|---|
| ソースが Lockfile のエントリと一致し、翻訳先が存在する | なし | |
どの files パターンにもファイルが一致しない | no-source-files | files パターンを修正する |
| 前回の翻訳以降にソースが変更された | source-changed | lingo push --wait、またはプッシュがまだ実行中の場合は lingo pull |
| ソースに対応する Lockfile のエントリがない | source-not-pushed | lingo push --wait |
| 翻訳先ファイルがなく、ソースは最新の状態である | missing-target | lingo push --backfill-missing --wait |
| 翻訳先ファイルがなく、ソースが変更されたか、一度もプッシュされていない | missing-target | lingo push --wait |
| 翻訳先ファイルが手動で編集された | なし | |
| Lockfile がなく、すべての翻訳先ファイルが存在する | なし。標準エラー出力に注記を表示 | |
| Lockfile がなく、翻訳先ファイルが不足している | missing-target。標準エラー出力に注記を表示 | lingo push --backfill-missing --wait を実行してから、翻訳先ファイルと .lingo/lock.json をコミットする |
ソースとして設定されなくなったパスの Lockfile エントリは無視されます。lingo push が表示する翻訳先の推定と YAML のスキップに関する警告は、ここでも標準エラー出力に表示されます。
報告された問題の見方 #
| 種類 | 検討する修正方法 |
|---|---|
missing-context | 抽出されたメッセージに、役立つコンテキストを追加します。 |
stale-jsonc | ソースカタログを再生成し、内容を確認します。 |
stale-types | 宣言を再生成し、アプリケーションの型チェックの対象に含めます。 |
missing-translation | 有効なキーのうち、有効な翻訳先の値が未設定または空のものを確認します。 |
orphaned | クリーンアップする前に、メッセージが削除されたのか、抽出から漏れたのかを確認します。 |
ファイルチェックで報告される問題と修正方法は、ファイルチェックを参照してください。
JSON 出力 #
JSON 出力には issues と stats が含まれます。ローカルで確認するための読みやすい形式の出力にも、同じ問題が一覧表示されます。
各問題には type と message があります。React チェックの問題には src が含まれることがあります。ファイルチェックの問題には file があり、missing-target の問題には locale もあります。
統計には messages、locales、missingContext、missingTranslations、orphaned、staleJsonc、staleTypes が含まれます。React チェックが実行されなかった場合、これらの値はゼロまたは偽になります。ロケール数には、検出された翻訳先に加えてソースも含まれます。ファイルチェックが実行された場合、stats.files には lockfile、sources、locales、changedSources、missingTargets が含まれます。これらが示すのは整合性であり、言語品質の測定結果ではありません。
CI で実行する #
フォークからのものも含め、すべてのプルリクエストまたはマージリクエストで実行してください。
- uses: actions/checkout@v4
- run: npx @lingo.dev/cli@latest check抽出時と同じ入力を使用する #
--src、--out、--types、--source-locale は React チェックにのみ適用されます。--src の既定値は src、--source-locale の既定値は en です。カタログパスは --out、設定済みのカタログパス、locales の順に優先されます。宣言パスは --types、設定済みの宣言パス、lingo.d.ts の順に優先されます。パスはプロジェクトルートを基準に解決されます。ソースロケールの既定値は、ローカライズ設定とは独立しています。--json の既定値は偽で、両方のチェックに適用されます。
最新の状態に更新するには、同じ入力で抽出を実行してください。警告と差分を確認してから、チェックとアプリケーションのビルドを再実行します。不要になったことを確認できたエントリだけを削除し、その後で宣言を再生成してください。
制限事項 #
- ファイルチェックはファイル単位で動作します。既存の翻訳先ファイル内でキーが欠落していても、React の
.jsoncカタログ内を除き、報告されません。 .xcstringsファイルなど、単一の共有カタログ内のロケールはチェックされません。また、カタログ内を手動で編集すると、ソースの変更として扱われます。- CLI から GitHub App に移行したリポジトリでは、
.lingo/lock.jsonを削除してください。 - 複数のソースが同じ翻訳先に解決される場合や Lockfile が破損している場合など、設定エラーが発生すると、標準エラー出力にメッセージを表示し、JSON を出力せずに終了コード 1 で終了します。
- ソースのハッシュはバイト単位で厳密に計算されるため、
lingo pushを実行したチェックアウトと CI のチェックアウトでは、同じ改行コードを使用する必要があります。.gitattributesに* text=auto eol=lfを追加してください。
React カタログの場合、翻訳先はカタログディレクトリ内の .jsonc ファイルです。files パターンがソースカタログ(locales/en.jsonc など)に一致する場合は、設定されたすべての翻訳先ロケールのファイルも必要です。
コンテキストの問題として扱われるのは、抽出時のコンテキスト不足の警告だけです。動的な式に関する警告や競合情報が、ここですべて失敗判定の対象になるわけではありません。競合があれば、抽出処理自体が失敗します。また、ソース言語のプレースホルダーが空でなければ、翻訳されていなくても存在チェックに合格することがあります。
生成結果がバイト単位で最新かどうかだけを確認する場合は、extract --check を使用してください。このチェッカーと併せて、各形式に対応した検証とコンテンツのレビューも続けてください。チェックに合格しても、実際のチェック範囲外にある Android リソース、Markdown の描画、翻訳の意味については何も保証されません。