Automatizujte překlady v CI

Zařaďte překlad do opakovatelného procesu vydávání — od známé revize zdroje přes ověřené soubory až po kontroly aplikace.

Pipeline pro vydávání už propojuje revizi zdroje s výsledkem, který mohou lidé používat. Překlad by měl tuto návaznost zachovat. Úloha musí vědět, který zdroj se změnil, stáhnout odpovídající cílové soubory a předat dalšímu kroku dostatek podkladů k jejich přijetí nebo odmítnutí.

Složité situace přicházejí po prvním úspěšném požadavku: někdo ještě upravuje překlad při kontrole, runner přestane být dostupný nebo dorazí novější revize zdrojového textu dřív, než se dokončí překlad té starší. Tento průvodce vás provede sestavením procesu CI, který tyto situace zvládne, aniž by publikoval zastaralé soubory nebo zbytečně přepisoval schválené úpravy. Konfiguraci YAML pro jednotlivé poskytovatele najdete v návodech pro GitHub Actions, GitLab, Bitbucket a Buildkite.

Rozhodněte, v jakém kroku vydání zapojíte překlady #

Pokud vám vyhovuje workflow, které pro repozitáře nabízí spravovaná GitHub App, použijte ji. Změny ve výchozí větvi vytvoří pull request s překlady; volitelné zpracování pull requestů zapisuje do větve příslušného pull requestu. Schválením spuštění povolíte práci na překladu. Kontrola obsahu a sloučení přicházejí až poté.

Při použití runneru s CLI přebírá vaše pipeline odpovědnost za odeslání požadavku, stažení výsledků i jejich doručení. Vyberte cíl, který odpovídá vašemu procesu vydávání:

CílJaké rozhodnutí umožňuje
Pouze artefaktJiná úloha nebo člověk zkontroluje výstup před provedením změn v repozitáři nebo vydání.
Větev s překlady a pull requestZměny v překladech zkontrolujete samostatně, než se dostanou do výchozí větve.
Větev zdrojového pull requestuZdroj i překlady zkontrolujete společně v rámci jedné změny.
Přímý commit do výchozí větvePřeklady doručíte bez samostatného pull requestu tam, kde to pravidla větve výslovně dovolují.

Pro daný stav překladů určete jediný aktivní proces, který smí zapisovat do repozitáře. Jinak si dva runnery pracující s různými revizemi zdroje mohou navzájem konkurovat při commitování souborů a souboru Lockfile. Pro generované commity nastavte také pravidla podle větve, cesty nebo samotného generovaného commitu, aby znovu a znovu nespouštěly překlad.

Připravte výchozí stav, který runner převezme #

Než zapnete opakované spouštění, přeložte lokálně jeden zdrojový soubor do jednoho jazyka a spusťte kontroly prostředků aplikace. Konfiguraci, přijatý cílový soubor a .lingo/lock.json uložte společně do jednoho commitu. Čistý checkout by měl vést ke stejnému výběru zdrojů i uspořádání cílových souborů.

Příklady pro jednotlivé poskytovatele mají pevně nastavenou verzi @lingo.dev/cli@1.21.0. Při nastavování workflow ji nahraďte aktuálním vydáním CLI. Chcete-li CLI spravovat spolu se závislostmi projektu, nainstalujte ho pomocí npm install --save-dev --save-exact @lingo.dev/cli@1.21.0 a uložte package.json a package-lock.json do commitu. Poté pomocí npm ci a npx --no-install lingo spouštějte verzi zaznamenanou v souboru Lockfile.

.lingo/config.json určuje jazyky, vzory pro výběr souborů a lokalizační engine. Přístup k organizaci a lokalizačnímu engine nastavte už při počáteční konfiguraci. Pokud úloha potřebuje inicializovat nebo propojit projekt, použijte explicitní volby z referenční dokumentace Inicializace a Propojení, aby při běhu bez obsluhy nečekala na odpověď na výzvu.

V monorepozitáři před spuštěním CLI přejděte do balíčku s požadovanou konfigurací. Vzory zadané jako poziční argumenty zužují výběr zdrojů v této konfiguraci; nevybírají konfiguraci jiného balíčku. U každého samostatně nakonfigurovaného balíčku udržujte stav a cesty k artefaktům pohromadě.

LINGO_API_KEY předejte prostřednictvím mechanismu runneru pro správu tajných údajů. Funguje bez interaktivního přihlášení. Úlohy s přihlašovacími údaji spouštějte pouze z důvěryhodného kódu, protože změny skriptů ve větvi mohou klíč odhalit. Omezení pro chráněné proměnné a forky mají určovat, kde se úloha smí spustit. Neodstraňujte je jen proto, aby nedůvěryhodná úloha uspěla.

Zadejte správný typ překladové úlohy #

Při prvním překladu z čistého stavu požádejte o vytvoření chybějících cílových souborů. V existujícím projektu nejprve zpracujte běžné změny zdroje pro stávající cílové soubory, stáhněte výsledky a zkontrolujte je. Teprve potom přidejte chybějící jazyky a doplňte překlady, aniž byste měnili revizi zdroje. Před spuštěním tohoto příkazu postupujte podle návodu Přidání jazyka:

sh
lingo push --backfill-missing --wait

Pro změny zdroje oproti připravenému výchozímu stavu:

sh
lingo push --wait

První běžný push může zaznamenat stav zdroje, aniž by ho přeložil. Zpětné doplnění zadá úlohu pro chybějící soubory; pozdější běžné operace push určují rozsah práce podle změn zdroje. Push s omezeným rozsahem ani push pro zpětné doplnění není univerzálním řešením chybějících klíčů v existujících cílových souborech.

--wait počká na dokončení běhu a stáhne hotový výstup. Bez něj příkaz push skončí už po odeslání požadavku. Pokud čekáte na kontrolu nebo výsledky stahujete v samostatné úloze, je nutný postup pro zachování stavu běhu v CI: před ukončením runneru uchovejte konkrétní ukazatel uložený v domovském adresáři, který neobsahuje tajné údaje, původní absolutní cestu ke kořeni projektu a odpovídající stav zdroje, konfigurace, cílových souborů a souboru Lockfile. Obnovte je ve stejném kořenovém adresáři a samostatně proveďte autentizaci. Teprve pak použijte lingo pull --dry-run a následně lingo pull. Pokud runner nedokáže stejnou cestu znovu vytvořit, použijte místo toho trvalý checkout s příslušným oprávněním. Nikdy nearchivujte přihlašovací údaje ani celý obsah ~/.lingo.

Uchovejte návratový kód a hlášené výsledky pro jednotlivé cíle. Aktuální CLI při nahlášeném selhání cíle skončí chybou, při lidské kontrole ale může běh zůstat ve stavu čekání na rozhodnutí. Zatímco nová verze čeká, starý soubor může stále existovat. Než úloze pro doručení povolíte publikování výsledku, dokončete kontrolu a výsledek stáhněte.

Přesné chování příkazů najdete v dokumentaci Push a Pull. --yes přeskočí potvrzení vynuceného opětovného generování; nenahrazuje schválení při lidské kontrole ani nepromění všechny čekající akce v dokončenou práci.

CLI v CI přeskakuje kontroly aktualizací. LINGO_DISABLE_UPDATE_CHECK=1 a LINGO_TELEMETRY_DISABLED=1 umožňují toto chování v případě potřeby výslovně řídit, aniž byste vypnuli síťovou komunikaci potřebnou pro překlad.

Ověřte, že má další krok použitelné soubory #

Ověřte očekávanou změněnou položku oproti revizi zdroje. Samotná existence souboru není dostatečným důkazem, pokud checkout už obsahuje starší cílový soubor. Uchovejte stažený výstup i stav souboru Lockfile ze stejné operace. Jazyky, jejichž zpracování selhalo nebo stále čeká, ponechte viditelně označené jako nedokončené.

Poté použijte kontroly přizpůsobené danému typu prostředku:

  • Při extrakci pro React spusťte lingo extract --check, lingo check, kontrolu TypeScriptu v projektu a samotné sestavení aplikace. Každá z těchto kontrol prověřuje jinou část výsledku.
  • U nativních prostředků spusťte generování nebo kompilaci prostředků dané platformy.
  • U statického obsahu zpracujte přeložené dokumenty parserem a zkontrolujte odkazy, proměnné a zachování syntaxe.
  • Chcete-li, aby požadavek na sloučení při neaktuálních překladech neprošel, spusťte lingo check. Klíč API není potřeba.

lingo check pracuje na úrovni souborů: pro každý nakonfigurovaný jazyk hlásí změněný zdroj a chybějící cílový soubor, nikoli chybějící klíč uvnitř existujícího souboru Android, Apple, ARB nebo Markdoc.

V rámci zvoleného procesu přijetí ověřte také význam překladu. Sestavení může odhalit nesprávný formát prostředku, ale přesto přijmout větu, která mění důležitou podmínku. Po úspěšném dokončení kontrol a kontroly obsahu uložte do commitu nebo publikujte jen soubory na zamýšlených výstupních cestách. Zachovejte možnost ukončení bez změn a nechte selhání povinných kontrol ukončit úlohu chybou, místo abyste je maskovali bezpodmínečným commitem.

Než zadáte náhradní úlohu, navažte na zaznamenaný běh #

Po přerušení úlohy obnovte identifikátor jejího běhu a výsledky pro jednotlivé cíle. Pokud už se překlad dokončil, stáhněte jeho výstup před odesláním dalšího požadavku. Pokud se během čekání změnil lokální cílový soubor, vyřešte konflikt při stahování s přijatou úpravou před očima. Vynucené přepsání může zahodit právě tu opravu, kterou má workflow zachovat.

Během diagnostiky soubor Lockfile nemažte. Jeho odstraněním změníte výchozí stav zdroje pro další běh a z úzce zaměřené obnovy se může stát jiná úloha. Prohlédněte si rozdíly a znovu spusťte jen tu část, která zůstává nedokončená. Tento postup rozhodování podrobněji popisuje návod Obnovení přerušeného běhu lokalizace.

Než nastavíte plánované spouštění úlohy, vyzkoušejte kromě úspěšného průběhu také jedno čekání na lidskou kontrolu a jedno přerušené stahování. Krok vydání by měl zachovat poslední přijatý stav a označit nedokončený jazyk, ne přijmout jakýkoli soubor, který zrovna existuje.