Lockfile a cache

Při aktualizacích a obnově udržujte propojené výchozí stavy zdrojů, hashe cílů, vzdálené artefakty a lokální ukazatel běhu.

Inkrementální překlad potřebuje vědět, co se změnilo. .lingo/lock.json zaznamenává hashe zdrojů a cílů, server uchovává artefakty a výstup překladu a lokální ukazatel v domovském adresáři určuje nejnovější běh, jehož výsledky se mají načíst. Každý z těchto prvků slouží jiné operaci, takže odstranění jednoho není univerzálním řešením problémů s ostatními.

Výchozí stav projektu #

Lockfile používá verzi 1 a mapu files, která cestám relativním vůči repozitáři přiřazuje hashe SHA-256:

json
{
  "version": 1,
  "files": {
    "locales/en.json": {
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  }
}

Tento hash je jen ukázkou formátu, nikoli hodnotou ke zkopírování. Hashe zdrojů identifikují předchozí bajtový obsah pro inkrementální porovnání. Hashe cílů pomáhají odhalit ruční úpravy před načtením výsledků. Soubor neobsahuje přeložený text ani hodnocení kvality.

Zahrňte Lockfile do commitu spolu se schválenými změnami zdrojů a cílů, které popisuje. Pokud stav chybí, push postupuje jako při vytváření prvního výchozího stavu. Pokud je stav poškozený nebo nepodporovaný, operace selže, místo aby jej bez upozornění resetovala.

Kdy se hashe aktualizují #

Při načtení výsledků se zaznamenají hashe dokončených cílů. Samotné odeslání bez načtení výsledků výchozí stav definitivně nepotvrdí. Každý dokument se dokončuje samostatně a jeho jednotlivé cíle zůstávají pozdržené, dokud nejsou dokončeny všechny. Existující výchozí stav celého zdroje se aktualizuje pouze tehdy, když dokument pokrývá všechny nakonfigurované cílové jazyky, všechny cíle jsou dokončené a není nastaveno omezení na konkrétní klíče. Načtení výsledků jen pro některé jazyky ponechá tento výchozí stav pro ostatní beze změny; pokud záznam zdroje dosud neexistuje, může jej vytvořit. Obnovení klíče ponechá hash zdroje beze změny bez ohledu na to, zda výsledky načte push --wait, nebo pull.

Artefakty a překlady v cache #

Artefakty se adresují podle obsahu, takže push nahrává pouze bajty, které server ještě nemá. Předchozí zdroj uvedený v souboru Lockfile musí být možné obnovit z lokálního bajtového obsahu nebo ze serveru. Pokud není dostupný ani na jednom místě, zkontrolujte příslušný záznam v souboru Lockfile a obnovte bajtový obsah, o němž víte, že je správný, nebo konzistentní výchozí stav. Nenahrazujte hash odhadnutou hodnotou.

Výstup překladu uložený v cache není totéž co úložiště zdrojů. Odstranění lokálního cíle nezaručuje, že pozdější požadavek spustí model znovu.

Ukazatel nejnovějšího běhu #

~/.lingo/runs/<project-hash>.json identifikuje nejnovější push pro danou absolutní cestu ke kořenovému adresáři projektu. Obsahuje ID běhu, organizace a lokalizačního engine, zdrojový jazyk a čas vytvoření. Dokud nejsou výsledky operace push načtené, uchovává také identitu požadavku, díky níž může opakovaný push znovu použít původní odeslání, místo aby vytvořil duplicitní.

Nejde o .lingo/run.json a nepřenáší se prostřednictvím Gitu. Po přesunutí checkout nebo na jiném runneru může ukazatel chybět i při totožné konfiguraci a souboru Lockfile. Nový push jej může nahradit. Původní identitu běhu uchovejte v provozních záznamech bez tajných údajů, dokud nebude načítání výsledků dokončeno.

Uchování běhu pro jinou úlohu CI #

Pokud čekáte na kontrolu nebo máte odesílání a načítání výsledků rozdělené do samostatných úloh, uchovejte ukazatel dříve, než odesílající runner zanikne. Následující příkaz spusťte z adresáře určeného absolutní cestou, který obsahuje požadovaný .lingo/config.json, ihned po odeslání a před dalším spuštěním push:

sh
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

Tyto dva soubory obsahují ukazatel běhu bez tajných údajů a přesnou absolutní cestu ke kořenovému adresáři projektu, podle které se ukazatel vyhledává. Ověřte, že runId v exportovaném JSON odpovídá ID vypsanému při tomto odeslání. Pokud odeslání selže před zaznamenáním nového běhu, může zůstat uložený předchozí ukazatel. Ověřené soubory uchovejte jako artefakty úlohy s řízeným přístupem spolu s revizí zdroje, .lingo/config.json, .lingo/lock.json a odpovídajícími zdrojovými a cílovými soubory, včetně výstupu nezahrnutého do commitu. U příkladů CI s jedním souborem uchovejte locales/en.json a locales/es.json; u jiného projektu použijte skutečně vybrané cesty. Pokud zdroj a cíle používají jeden soubor, uchovejte celý sdílený katalog. Nastavte dobu uchování artefaktů tak, aby stačila na kontrolu i načtení výsledků. Nikdy nearchivujte celý obsah ~/.lingo, soubory s přihlašovacími údaji ani tajné hodnoty proměnných prostředí.

Po kontrole obnovte stejnou revizi a uchovaný stav souborů ve stejném absolutním kořenovém adresáři projektu na autorizovaném runneru. Nainstalujte stejnou verzi CLI a přihlašovací údaje předejte odděleně prostřednictvím mechanismu runneru pro správu tajných údajů. Z tohoto kořenového adresáře obnovte pouze tento ukazatel:

sh
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

Ověřte, že uvedený běh odpovídá tomu, který jste uchovali, vyřešte případné konflikty, pak použijte lingo pull a zkontrolujte načtený výstup. Nespouštějte nejprve push, protože by ukazatel nahradil. Pokud služba CI nedokáže znovu vytvořit původní kořenový adresář, použijte pro odesílání i načítání výsledků trvalý autorizovaný runner s touto cestou. Pouhé zkopírování ukazatele do checkout umístěného jinde nestačí. Dočasný export .lingo-ci odstraňte až po načtení výsledků a uplynutí požadované provozní doby uchování. Nezahrnujte jej do commitů překladů.

Existující překlady a ruční úpravy #

Plánování s omezeným rozsahem nebo při úvodním nastavení může převzít existující cíle. Nejprve zkontrolujte jejich jazyk a úplnost: zástupné texty ve zdrojovém jazyce mohou projít kontrolou přítomnosti, aniž by šlo o překlady. Zpětné doplnění vytváří chybějící běžné soubory, nikoli chybějící klíče uvnitř existujícího souboru.

Při běžném inkrementálním zpracování se předávají úpravy cílových textů u nezměněných klíčů, aby zůstaly zachované. Změny zdrojových klíčů však mohou vést k jejich nahrazení. JSON používá jako identifikátory cesty ke klíčům, takže přejmenování klíče znamená nové zpracování i při totožném znění zdroje. To se liší od opětovného využití podle otisku obsahu ve verzi v0.

preservedKeys poskytuje výslovnou ochranu tam, kde má cílový text zůstat směrodatný. Vynucené zpracování celého souboru ale odstraňuje kontext aktuálního cíle, který je pro tuto ochranu potřeba. Pull před zápisem porovnává nově vypočtené hashe; samotný commit v Gitu toto porovnání nemění. Během přímého načítání výsledků pomocí push --wait cíle neupravujte.

Větve a souběžné zápisy #

Způsob práceDůsledek
Překlad ve větvi pro novou funkciKontrolujte zdroj i cíl společně; při rebase slaďte kolidující úpravy výchozího stavu.
PR s překladem po sloučení zdrojeSamostatná kontrola s prodlevou před přijetím přeložených změn.
PR s překladem z GitHub AppIntegrace řídí spouštění a zpětný zápis; schválení běhu je oddělené od sloučení.
Autorizovaný runner zapisuje přímo do větveVyžaduje výslovné oprávnění k zápisu, kontroly obsahu a ochranu před souběžnými zápisy.

Při konfliktu během slučování souboru Lockfile nejprve zjistěte, které revize zdroje a cílů jednotlivé strany popisují. Slaďte přijatý obsah a poté pomocí odpovídajícího workflow zachovejte nebo znovu sestavte konzistentní výchozí stav. Kombinování nesouvisejících hashů nebo odstranění souboru Lockfile jen kvůli potlačení konfliktu může skrýt nedokončený překlad.

Nastavení poskytovatele spadá pod GitHub App, GitHub Actions, GitLab, Bitbucket nebo Buildkite. Příkaz check porovnává nakonfigurované zdroje s tímto souborem Lockfile a hlásí chybějící cílové soubory. Klíče uvnitř těchto souborů kontroluje pouze u katalogů React .jsonc.

Další lokální stav v domovském adresáři #

~/.lingo/update-check.json ukládá výsledky kontrol verzí do cache na 24 hodin. Přihlašovací údaje a anonymní identita pro telemetrii se uchovávají odděleně. Žádné z těchto úložišť neobsahuje přeložené soubory. Než začnete odstraňovat stav, zjistěte pomocí části Řešení problémů, která operace selhala.