Lockfileとキャッシュ
更新時や復旧時も、ソースのベースライン、ターゲットのハッシュ、リモートのアーティファクト、ローカルの実行ポインターの対応関係を保ちます。
差分翻訳には、何が変わったかを把握する仕組みが必要です。.lingo/lock.jsonはソースとターゲットのハッシュを記録し、サーバーはアーティファクトと翻訳出力を保持します。ホームディレクトリ内のローカルポインターは、取得対象となる最新の実行を識別します。それぞれ異なる操作を担うため、どれかを削除しても、別の状態に起因する問題を解決できるわけではありません。
プロジェクトのベースライン #
Lockfileはバージョン1を使用し、リポジトリからの相対パスをSHA-256ハッシュに対応付けるfilesマップを持ちます。
{
"version": 1,
"files": {
"locales/en.json": {
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
}
}このハッシュは形式を示す例であり、そのままコピーして使う値ではありません。ソースのハッシュは、差分比較の基準となる以前のバイト列を識別します。ターゲットのハッシュは、取得前にローカルで加えられた編集を検出するために使われます。このファイルには、翻訳文も品質評価も含まれません。
Lockfileは、そこに記録された確定済みのソースとターゲットの変更と一緒にコミットしてください。状態が存在しない場合、プッシュは初回のベースラインを作成する動作になります。状態の形式が不正、または未対応の場合は、暗黙にリセットされるのではなく、エラーになります。
ハッシュが更新されるタイミング #
取得時に、完了したターゲットのハッシュが記録されます。送信するだけではベースラインは確定せず、取得が必要です。確定は文書ごとに行われ、その文書のすべてのターゲットが完了するまで、同じ文書のほかのターゲットも取得されません。既存のソース全体のベースラインが更新されるのは、その文書が設定済みのすべてのターゲットロケールを対象とし、すべてのターゲットが完了し、キーのスコープが設定されていない場合に限られます。一部のロケールだけを取得した場合は、ほかのロケールのために既存のベースラインが維持されます。ただし、ソースのエントリがなければ、取得時に初期化できます。キーの再翻訳では、push --waitとプルのどちらで取得しても、ソースのハッシュは変わりません。
アーティファクトと翻訳キャッシュ #
アーティファクトは内容に基づいて識別されるため、プッシュでアップロードされるのは、サーバーにないバイト列だけです。Lockfileに記録された以前のソースは、ローカルのバイト列かサーバーから復元できる必要があります。どちらにもない場合は、該当するLockfileのエントリを調べ、正常であると確認済みのバイト列、または整合性のあるベースラインを復元してください。推測したハッシュで代用しないでください。
翻訳出力のキャッシュと、ソースの保存は別の仕組みです。ローカルのターゲットを削除しても、その後のリクエストでモデルが新たに呼び出されるとは限りません。
最新の実行を指すポインター #
~/.lingo/runs/<project-hash>.jsonは、絶対パスで指定されたプロジェクトルートに対する最新のプッシュを識別します。実行、組織、ローカライゼーションエンジンの各IDに加え、ソースロケールと作成日時が含まれます。そのプッシュの結果を取得するまでは、リクエストの識別情報も保持されます。これにより、プッシュを繰り返しても送信が重複せず、既存の送信を再利用できます。
これは.lingo/run.jsonとは異なり、Gitで共有されるものではありません。設定とLockfileが同じでも、チェックアウト先を移動した場合や別のランナーを使う場合は、ポインターが存在しないことがあります。また、新しいプッシュによって置き換わることもあります。取得が完了するまでは、元の実行の識別情報を、機密情報を含まない運用記録に残してください。
別のCIジョブに引き継ぐ実行情報を保持する #
レビュー待ちがある場合や、送信と取得を別々のジョブで行う場合は、送信側のランナーが破棄される前にポインターを保存してください。送信直後、次のプッシュを行う前に、目的の.lingo/config.jsonを含むディレクトリの絶対パスを作業場所として、次を実行します。
node --input-type=module <<'JS'
import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
const root = process.cwd();
if (!existsSync(".lingo/config.json")) throw new Error("Run from the configured project root");
const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
mkdirSync(".lingo-ci", { recursive: true });
copyFileSync(join(homedir(), ".lingo", "runs", `${hash}.json`), ".lingo-ci/run.json");
writeFileSync(".lingo-ci/project-root.txt", root);
JSこの2つのファイルには、機密情報を含まない実行ポインターと、その保存場所の特定に使うプロジェクトルートの正確な絶対パスが含まれます。エクスポートしたJSONのrunIdが、今回の送信で表示されたIDと一致することを確認してください。新しい実行が記録される前に送信が失敗すると、以前のポインターが残ることがあります。確認済みのファイルは、ソースのリビジョン、.lingo/config.json、.lingo/lock.json、および対応するソースファイルとターゲットファイルとともに、アクセス制御されたジョブアーティファクトとして保持してください。未コミットの出力も含めます。単一ファイルを使うCIの例では、locales/en.jsonとlocales/es.jsonを保持してください。別のプロジェクトでは、実際に選択したパスを使用します。ソースとターゲットが1つのファイルを共有している場合は、共有カタログ全体を保存してください。アーティファクトの保持期間は、レビューと取得に十分な長さに設定します。~/.lingo全体、認証情報ファイル、環境変数の機密値は、決してアーカイブしないでください。
レビュー後、使用を許可されたランナーの同じ絶対パスのプロジェクトルートに、同じリビジョンと保存したファイルの状態を復元してください。同じバージョンのCLIをインストールし、認証情報はランナーのシークレット管理機能を通じて別途渡します。そのルートから、このポインターだけを復元してください。
node --input-type=module <<'JS'
import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
const root = readFileSync(".lingo-ci/project-root.txt", "utf8");
if (process.cwd() !== root || !existsSync(".lingo/config.json")) {
throw new Error("Restore the configured project at its original absolute root");
}
const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
const directory = join(homedir(), ".lingo", "runs");
mkdirSync(directory, { recursive: true });
const destination = join(directory, `${hash}.json`);
if (existsSync(destination)) throw new Error("Preserve the existing run pointer before replacing it");
copyFileSync(".lingo-ci/run.json", destination);
JS
lingo pull --dry-run表示された実行が保存したものと一致することを確認し、競合があれば解決してください。その後、lingo pullを実行し、取得した出力を確認します。先にプッシュするとポインターが置き換わるため、プッシュしないでください。CIサービスで元のルートを再現できない場合は、そのパスを持つ、使用を許可された永続ランナーで送信と取得を行ってください。別の場所にあるチェックアウト先へポインターをコピーするだけでは不十分です。一時的な.lingo-ciのエクスポートは、取得と運用上必要な保持が完了してから削除し、翻訳のコミットには含めないでください。
既存の翻訳と人による編集 #
スコープを限定した処理や初期化の計画では、既存のターゲットを採用できます。まず、言語と翻訳の完成度を確認してください。ソース言語の仮置きテキストは、翻訳ではなくても存在チェックを通過することがあります。補完処理が作成するのは、不足している通常のファイルであり、既存ファイル内の不足しているキーではありません。
通常の差分処理では、ソースが変わっていないキーに対するターゲットの編集内容を、保持するために渡します。ソースのキーに変更がある場合は、その編集内容が置き換わることがあります。JSONではキーパスが識別子となるため、ソースの文言が同じでも、キー名を変更すると新たな処理が発生します。この点は、内容のフィンガープリントに基づいて再利用していたバージョン0とは異なります。
preservedKeysを使うと、ターゲットのテキストを正として維持したい場合に、明示的な保護を加えられます。ただし、ファイル全体を強制処理すると、この保護に必要な現在のターゲットの情報が失われます。プルは書き込み前に最新のハッシュを比較します。Gitでコミットするだけでは、この比較は変わりません。push --waitで直接取得している間は、ターゲットを編集しないでください。
ブランチと複数の書き込み元 #
| 運用方法 | 影響 |
|---|---|
| 機能ブランチで翻訳する | ソースとターゲットを一緒にレビューします。リベース時に、競合するベースラインの編集内容を調整します。 |
| ソースのマージ後に翻訳のプルリクエストを作成する | レビューを分けて行うため、翻訳の変更が取り込まれるまでに時間差が生じます。 |
| GitHub Appによる翻訳のプルリクエスト | 連携機能がトリガーと書き戻しを制御します。実行の承認は、マージとは別に行います。 |
| 使用を許可されたランナーがブランチに直接書き込む | 明示的な書き込み権限、内容の確認、複数の書き込み元による同時更新への対策が必要です。 |
Lockfileのマージで競合が起きた場合は、まず双方がそれぞれどのソースとターゲットのリビジョンを記録しているかを特定してください。採用する内容の整合性を取ったうえで、適切なワークフローを通じて、整合性のあるベースラインを保持するか再構築します。無関係なハッシュを組み合わせたり、競合を解消するためだけにLockfileを削除したりすると、未完了の翻訳が見えなくなることがあります。
プロバイダーの設定については、GitHub App、GitHub Actions、GitLab、Bitbucket、またはBuildkiteをご覧ください。checkは、設定済みのソースをこのLockfileと比較し、不足している翻訳先ファイルを報告します。ただし、Reactの.jsoncカタログを除き、ファイル内のキーまでは確認しません。
ホームディレクトリ内のその他のローカル状態 #
~/.lingo/update-check.jsonは、バージョン確認の結果を24時間キャッシュします。認証情報と匿名テレメトリの識別情報は、それぞれ別の場所に保存されます。いずれにも翻訳済みファイルの出力は保存されません。状態を削除する前に、トラブルシューティングで失敗した操作を特定してください。