Lingo check

翻訳が最新でなければ CI を失敗させ、React カタログもチェックします。

lingo check は、翻訳が最新でなければ失敗します。各ソースファイルを .lingo/lock.json と比較し、すべての翻訳先ファイルが存在することを確認します。@lingo.dev/react プロジェクトでは、抽出されたカタログ、宣言、コンテキスト、翻訳もチェックします。

sh
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-filesfiles パターンを修正する
前回の翻訳以降にソースが変更されたsource-changedlingo push --wait、またはプッシュがまだ実行中の場合は lingo pull
ソースに対応する Lockfile のエントリがないsource-not-pushedlingo push --wait
翻訳先ファイルがなく、ソースは最新の状態であるmissing-targetlingo push --backfill-missing --wait
翻訳先ファイルがなく、ソースが変更されたか、一度もプッシュされていないmissing-targetlingo 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 で実行する #

フォークからのものも含め、すべてのプルリクエストまたはマージリクエストで実行してください。

yaml
- 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 の描画、翻訳の意味については何も保証されません。