CLIのトラブルシューティング

復旧に役立つ状態情報を残したまま、ファイル選択、ベースライン、取得、カタログの問題を解決します。

障害を診断する際は、インストール済みのバージョン、実行したコマンド、作業ディレクトリ、エラー、影響を受けるパスを確認できるようにしておいてください。ログを共有する前に、認証情報を伏せてください。起動時や障害時の診断情報には、コマンドライン引数がそのまま含まれることがあります。

ソースファイルが一致しない #

最も近い階層にある.lingo/config.jsonを探してください。下位ディレクトリで実行したコマンドが、上位ディレクトリのプロジェクトを使用する場合があります。対象に含める設定は空でも優先されるため、patternより先にincludeを確認してください。除外設定はエントリごとに適用されるため、別のエントリで同じファイルが選択されることがあります。

docs/en/**/*など、サポートされているマッチャー構文を使い、シェルパターンは引用符で囲んで、対応する拡張子を確認してください。YAMLではyaml、yaml-root-key、yaml-openapiのいずれかを明示する必要があり、Android XMLではandroidが必要です。.txt、.csv、.propertiesのファイルには、それぞれの拡張子で終わるパターン、または"format": "txt"、"format": "csv"、"format": "properties"のいずれかが必要です。docs/en/**/*のように対象範囲が広いパターンでは、これらのファイルは対象外になります。また、txt、csv、propertiesのいずれかを指定すると、その拡張子を持たないファイルはすべて対象外になります。形式を明示しても、すべての拡張子が対象になるわけではありません。

意図しない場所に出力される #

出力パスの導出に関する警告を読み、出力先がアプリケーションの読み込み先と一致しているか確認してください。ソースロケールを示すパス要素が認識されない場合は、ロケールを挿入するフォールバックに頼らず、targetPathとsourceRootを定義してください。翻訳先ファイルはソースの検出対象に含めず、パスの衝突も確認してください。

ファイルを移動するだけでは、ベースラインは更新されません。XCStringsは単一のソースカタログを共有する設計で、通常のロケール別の構成とは異なります。出力パスを参照してください。

オプションが反映されない #

認識されないルート設定キーやファイル設定キーは、警告が表示されたうえで無視されます。スペルと、選択したハンドラーが実際に対応しているオプションを確認してください。カタログのパス設定を変更しても、プッシュのパターンは更新されません。また、抽出とチェックでは、ソースロケールの既定値がそれぞれ独立してenに設定されます。

ローカルでのスコア評価には、プロジェクトのJSONではなく、実行可能ファイルのlingo.config.tsが使われます。JSONの保護オプションが、マークダウンやほかの形式にも適用されるとは限りません。

ベースラインの成果物が見つからない #

Lockfileのハッシュが示す以前のソース成果物が、ローカルまたはサーバーに存在する必要があります。該当するエントリを調べ、正常と確認できているバイト列か、整合性のあるベースラインを復元してください。エラーを隠すために、架空のハッシュを設定したり、Lockfile全体を削除したりしないでください。

状態情報がない場合、通常の初回プッシュではソースのバイト列が保存されます。通常の翻訳先ファイルが欠けている場合は、補完処理が必要です。操作に必要な記録については、Lockfileとキャッシュを参照してください。

プルで競合が報告される #

lingo pull --dry-runを実行して、書き込みの判定を確認してください。翻訳先ファイルが、サーバーの出力、プッシュ時に記録されたバイト列、Lockfileのハッシュのいずれとも一致しない場合、書き込みはブロックされます。そのファイルをコミットしても、比較結果は変わりません。

編集内容を保持して整合させるか、既知のバージョンに復元してください。強制実行は、意図的に置き換える場合にのみ選んでください。push --waitにはプルのように最新の状態で競合を確認する処理がないため、実行中は翻訳先ファイルを編集しないでください。

処理が失敗した、または完了しない #

翻訳先ごとのエラーを確認し、処理待ち、レビュー待ち、失敗、出力の欠落を区別してください。実行が失敗すると、push --waitとプルは、完了したドキュメントを書き込んだ後、ゼロ以外の終了コードを返します。状態と実際のファイルを確認してください。

未完了の翻訳先がすべて人によるレビューを待っている場合、push --waitとプルは待機を終了し、その旨を表示します。すべてのロケールで処理が完了したドキュメントは取得できます。レビュー担当者の作業が終わったら、lingo pullを再実行してください。再度プッシュしても、レビュー待ちは解消されません。

実行が失敗した場合は、報告された原因を修正し、その処理に適したコマンドを再実行してください。通常のソース更新では、ソースを変更せず、ベースラインを保持したままlingo push --waitを使います。翻訳先ファイルが欠けている場合は、言語を追加するに従い、既存の翻訳先を最新にしてから、欠落ファイルの補完処理だけを再実行してください。単に再試行を要求するために、ソースを編集したり、強制フラグを指定したり、状態情報を削除したりする必要はありません。

プッシュは、送信したジョブ、または再接続したジョブの識別子を表示します。前回のプッシュの結果がまだ取得されておらず、リクエストに変更がない場合は、そのリクエストが再利用されます。ジョブが実行中であれば識別子は維持され、失敗していれば新しいジョブに置き換えられます。失敗したジョブの識別子を控え、次に表示されるJob行で識別子が変わっていることを確認してください。これは新たな送信を示すだけで、翻訳の成功を示すものではありません。翻訳先ごとの結果を確認し、出力を取得して差分をレビューしてください。--waitの実行中は、ローカルの翻訳先ファイルを変更しないでください。ローカルの編集内容を保護する必要がある場合は、プッシュと、競合チェック付きのプルを別々に実行してください。

インストール済みのクライアントが同じ失敗済みジョブを返す場合は、繰り返し送信せず、support@lingo.devにメールでお問い合わせください。CLIのバージョン、機密情報を除いたコマンド、以前の実行と今回返された実行の識別子、ソースのリビジョン、影響を受けるロケールとパス、タイムスタンプ、機密情報を伏せたエラーを記載してください。認証情報、非公開のソーステキスト、認証情報ファイルの原本は含めないでください。障害の調査中は、ローカルの実行ポインターとLockfileを保持してください。

実行ポインターの削除は、新たな翻訳を要求する確実な方法ではありません。プッシュの結果が未取得の間、ポインターは重複送信を防ぐためのリクエスト識別情報を保持しています。実行が見つからない場合は、使用しているマシン、プロジェクトルートの絶対パス、別のプッシュによってポインターが置き換えられていないかを確認してください。

カタログのチェックが失敗する #

チェック時と同じロケールとパスを指定して抽出してください。孤立した項目を削除する前に、動的な呼び出しや分割代入を使った呼び出しに関する警告を確認してください。翻訳先ファイルの欠落が報告されるのは、filesのパターンがソースカタログに一致する場合だけです。一致しない場合は、想定されるロケールと既存のファイルを比較してください。

意図的に削除した項目だけを整理し、宣言を再生成してから、チェックとアプリケーションのビルドを実行してください。statusはチェックに移動しました。内部サービス名は、実行可能なコマンドではありません。

削除する前に #

パージでは、翻訳先ファイルの削除をプレビューできます。ファイルとロケールのフィルターを使うと、削除対象を、選択した翻訳先と対応するLockfileのエントリに限定できます。フィルターなしでパージすると、Lockfile全体が削除されます。共有のXCStringsカタログはスキップされます。パージは、削除そのものが目的の場合に使ってください。ほとんどの復旧作業では、承認済みの表現と復元可能な状態を保持したまま、問題のある箇所を修正する必要があります。