Postup pro GitLab CI
Překládejte soubory v důvěryhodné pipeline GitLab, předávejte je prostřednictvím žádosti o sloučení a označujte žádosti s neaktuálními překlady jako neúspěšné.
Runner GitLab může pomocí Lingo.dev CLI překládat soubory v repozitáři a uchovávat výsledky jako artefakty úlohy. Překlad tak využívá stejný checkout, kontroly i proces vydávání jako zbytek aplikace. GitLab zajišťuje spouštění pipeline a doručování výsledků do repozitáře; Lingo.dev zpracovává vybrané zdrojové soubory prostřednictvím lokalizačního engine.
Jde o postup pro CI, nikoli o nativní propojení s účtem GitLab. Začněte ručně spuštěnou pipeline ve výchozí větvi. Teprve po kontrole výsledku přidejte opakované spouštěče a předávání výsledků prostřednictvím žádostí o sloučení.
Připravte zdroj a přihlašovací údaje #
Projděte na svém počítači rychlý úvod do CLI. Zahrňte do commitu .lingo/config.json, schválené cílové soubory a .lingo/lock.json. Konfigurace určuje zdrojový jazyk, cílové jazyky, vzory souborů a lokalizační engine. CLI spouštějte z adresáře, který tuto konfiguraci obsahuje.
Chybějící cílové soubory vytvořte pomocí lingo push --backfill-missing --wait. Při dalších úpravách zdroje používejte běžný příkaz lingo push --wait. Samotná změna instrukcí lokalizačního engine schválené soubory nepřepíše; záměrné opětovné generování je samostatný úkol.
V nastavení proměnných CI/CD projektu uložte LINGO_API_KEY jako maskovanou proměnnou. CLI čte pouze tento název; proměnnou LINGODOTDEV_API_KEY z předchozí verze CLI ignoruje, proto ji přejmenujte. Zpřístupněte ji jen důvěryhodným větvím nebo prostředím, které smějí odesílat úlohy k překladu. Chráněná proměnná nemusí být v nechráněné větvi nebo žádosti o sloučení dostupná. Místo jejího zpřístupnění nedůvěryhodnému kódu použijte větev s potřebným oprávněním.
Klíč API opravňuje k překladu. Přihlašovací údaje pro GitLab s právem zápisu do repozitáře potřebujete až ve chvíli, kdy přidáte doručování výsledků pomocí commitů.
Příklady používají pevně nastavenou verzi CLI 1.21.0. lingo check kontroluje soubory překladů od verze CLI 1.20.0. Chcete-li verzi spravovat pomocí závislostí projektu a souboru Lockfile, postupujte podle průvodce nastavením CI.
Spusťte pipeline s ukládáním výsledků nejprve do artefaktů #
Tento příklad pro .gitlab-ci.yml předpokládá, že locales/en.json je nastavený zdroj a existující španělský soubor locales/es.json je jeho jediným cílem. Pokud máte více cílů, spusťte test -s a kontroly JSON pro každý cílový soubor zvlášť. V ostatních příkazech, které uvádějí locales/es.json, vypište cesty ke všem cílovým souborům. Lockfile zaznamená zdroj jako přeložený, takže se při pozdějším odeslání změn přeskočí a cíl vynechaný z artefaktu nebo commitu zůstane neaktuální. Příklad používá ručně spouštěnou pipeline ve výchozí větvi:
stages:
- translate
translate_catalog:
stage: translate
image: node:22
rules:
- if: '$CI_PIPELINE_SOURCE == "web" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
script:
# Replace 1.21.0 with the current CLI version.
- npx -y @lingo.dev/cli@1.21.0 push --wait
- test -s locales/es.json
- node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
- git diff -- locales/es.json .lingo/lock.json
artifacts:
paths:
- locales/es.json
- .lingo/lock.json--wait zajistí, že úloha počká na dokončení běhu a zapíše přeložené soubory do checkout. Bez něj lingo push pouze odešle požadavek na spuštění běhu a skončí, takže další kroky nenajdou žádné nové soubory ke kontrole ani k zahrnutí do commitu.
Ověřte, že má runner přístup k registru, a zajistěte všechny nástroje potřebné pro další kroky. Například při použití jiného minimálního obrazu může být nutné nejprve nainstalovat Git, aby bylo možné zkontrolovat rozdíly nebo vytvořit commit.
V souboru .lingo/config.json uloženém v commitu ověřte ID organizace a engine. Proveďte jednu úpravu zdroje a spusťte pipeline. V logu zkontrolujte hlášený stav běhu a změněnou cílovou položku. Stáhněte artefakt, porovnejte překlad s příslušnou revizí zdroje a načtěte jej v aplikaci. Samotná kontrola přítomnosti souborů a formátu JSON neověří aktuálnost ani význam překladu.
--wait stáhne hotový výstup. Pokud je ale nastavena lidská kontrola, může práce zůstat čekat na člověka. Než přidáte čekání na kontrolu nebo samostatnou úlohu pro načtení výsledků, zaveďte postup pro zachování stavu běhu v CI. Po odeslání exportujte konkrétní ukazatel a původní absolutní cestu ke kořenovému adresáři projektu. Do artefaktů úlohy s omezeným přístupem zahrňte .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, cílový soubor a soubor Lockfile. V konfiguraci artifacts nastavte when: always a zvolte dostatečně dlouhou dobu uchování pro dokončení kontroly. Zajistěte, aby se export provedl i při selhání následné validace; původní chybu nezakrývejte.
Dokončete kontrolu a poté na runneru pro načtení výsledků obnovte zaznamenanou revizi a stav souborů pod stejnou absolutní cestou ke kořenovému adresáři. Obnovte pouze daný ukazatel, autentizaci proveďte samostatně a před stažením výsledků použijte lingo pull --dry-run. Pokud runner nedokáže obnovit původní cestu, použijte pro obě úlohy trvalý runner s potřebným oprávněním. Nikdy nearchivujte celý obsah ~/.lingo. Samotné úspěšné odeslání ani starý cílový soubor nezajistí nové soubory k publikování.
Uložte překlady do commitu v žádosti o sloučení #
Tato úloha překládá změny zdroje v žádosti o sloučení a ukládá výsledky do commitu ve stejné větvi. Předpokládá, že počáteční doplnění už je uloženo v commitu a lidská kontrola je u engine vypnutá, takže překlad může být dokončen v jediné úloze.
V GitLab 18.4 nebo novějším zapněte Nastavení → CI/CD → Oprávnění tokenu úlohy → Povolit požadavky Git push do repozitáře. Úloha používá vestavěný token GitLab; osoba, která ji spouští, musí mít oprávnění odesílat změny do zdrojové větve. Viz nastavení tokenu úlohy v GitLab.
Pro LINGO_API_KEY ponechte zapnuté maskování a ochranu. Používejte důvěryhodné zdrojové a cílové větve ve stejném projektu, zapněte ochranu obou větví a v nastavení CI/CD projektu aktivujte Povolit pipeline žádostí o sloučení přístup k chráněným proměnným a runnerům. Osoba spouštějící pipeline musí mít také oprávnění odesílat nebo slučovat změny do cílové větve. To jsou požadavky GitLab na chráněné proměnné.
Použijte stejné zdrojové a cílové cesty jako v prvním příkladu. Přidejte tuto úlohu do fáze translate:
translate_merge_request:
stage: translate
image: node:22
resource_group: lingo-mr-$CI_MERGE_REQUEST_IID
rules:
- if: >-
$CI_PIPELINE_SOURCE == "merge_request_event" &&
$CI_MERGE_REQUEST_EVENT_TYPE == "detached" &&
$CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_MERGE_REQUEST_TARGET_PROJECT_ID
script:
# Replace 1.21.0 with the current CLI version.
- npx -y @lingo.dev/cli@1.21.0 push --wait
- test -s locales/es.json
- node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
- git add -- locales/es.json .lingo/lock.json
- if git diff --cached --quiet; then exit 0; fi
- git config user.name "Localization bot"
- git config user.email "localization@example.com"
- git commit -m "Update translations"
- git push "$CI_REPOSITORY_URL" "HEAD:refs/heads/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"resource_group zajišťuje, aby pro každou žádost o sloučení (MR) běžela vždy jen jedna překladová úloha. Úloha zahrne do commitu pouze cílový soubor ve španělštině a překladový soubor Lockfile. Pokud se větev během překladu změní, Git odeslání odmítne; spusťte pipeline pro aktualizovanou větev.
CI_REPOSITORY_URL poskytuje přihlašovací údaje tokenu úlohy. Odeslání změn s tímto tokenem nespustí další pipeline, proto před krok vytvoření commitu přidejte kontroly prostředků aplikace. V MR zkontrolujte rozdíly v překladu a před sloučením spusťte všechny zbývající kontroly.
Protože toto odeslání změn nespustí žádnou pipeline, nejnovější commit žádosti o sloučení žádnou nemá. Pokud je v projektu vyžadováno nastavení Pipeline musí uspět, GitLab může sloučení zablokovat. V takovém případě na kartě Pipeline dané žádosti o sloučení vyberte Spustit pipeline. Úloha nenajde nic k odeslání a skončí bez vytvoření commitu. Tato pipeline pak nejnovějšímu commitu přiřadí stav.
Otevřete žádost o sloučení překladů z výchozí větve #
Tato úloha přeloží každou změnu, která se dostane do výchozí větve, a otevře žádost o sloučení s výsledkem. Volby příkazu push v GitLab vytvoří žádost o sloučení v rámci stejného git push, takže není potřeba volat API ani používat další nástroj. Platí stejné předpoklady jako u předchozí úlohy: počáteční doplnění překladů je uloženo v commitu a lidská kontrola je vypnutá.
Vytvořte přístupový token projektu s rolí Vývojář a rozsahem write_repository. Uložte ho jako maskovanou a chráněnou proměnnou CI/CD s názvem GITLAB_PUSH_TOKEN. Na GitLab.com vyžadují přístupové tokeny projektu placený tarif. CI_JOB_TOKEN se zde nepoužívá, protože GitLab při odeslání změn s tímto tokenem nespustí žádnou pipeline. URL pro odesílání změn používá CI_SERVER_FQDN, čímž se zachová i nestandardní port instance ve vlastní správě. CI_SERVER_FQDN vyžaduje GitLab 16.10 nebo novější. U starší instance ve vlastní správě použijte místo toho ${CI_SERVER_HOST}:${CI_SERVER_PORT}.
Přidejte tuto úlohu do fáze translate:
translate_default_branch:
stage: translate
image: node:22
resource_group: lingo-translations
rules:
- if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
script:
- git fetch --quiet "$CI_REPOSITORY_URL" "$CI_DEFAULT_BRANCH"
- if [ "$(git rev-parse FETCH_HEAD)" != "$CI_COMMIT_SHA" ]; then exit 0; fi
# Replace 1.21.0 with the current CLI version.
- npx -y @lingo.dev/cli@1.21.0 push --wait
- test -s locales/es.json
- node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
- git add -- locales/es.json .lingo/lock.json
- if git diff --cached --quiet; then exit 0; fi
- git config user.name "Localization bot"
- git config user.email "localization@example.com"
- git commit -m "Update translations"
- >-
git push --force
-o ci.skip
-o merge_request.create
-o merge_request.target="$CI_DEFAULT_BRANCH"
-o merge_request.title="Update translations"
"https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_FQDN}/${CI_PROJECT_PATH}.git"
"HEAD:refs/heads/lingo/translations"Pokud některý cíl neprojde kontrolou, lingo push --wait skončí s nenulovým stavovým kódem, takže se úloha zastaví ještě před vytvořením commitu. Pokud se nic nezměnilo, vypíše "Nothing to push", rozdíl připravený k commitu je prázdný a úloha skončí bez vytvoření commitu.
První dva řádky zastaví úlohu, pokud se výchozí větev posunula za commit, na kterém úloha běží. resource_group spouští vždy jen jednu úlohu, ale ve výchozím režimu zpracování unordered v GitLab spouští čekající úlohy bez pevně daného pořadí. Bez této kontroly by starší úloha mohla běžet jako poslední a vynuceným odesláním přepsat novější překlady staršími. Úloha pro nejnovější commit přeloží jeho obsah; pro commit, který už není aktuální, se nic neodešle.
Úloha se nezacyklí. Spouští se pouze při odeslání změn do výchozí větve a zapisuje pouze do lingo/translations. Dokumentace GitLab uvádí, že -o ci.skip ovlivňuje pouze pipeline větví, nikoli pipeline žádostí o sloučení. Pipeline žádosti o sloučení se podle ní spustí při vytvoření žádosti nebo při přidání nového commitu do její zdrojové větve. Níže uvedená kontrola by se tedy měla spustit i pro žádost o sloučení překladů; při prvním spuštění si to ověřte. Sloučením této žádosti se úloha spustí ještě jednou, ale nenajde nic k odeslání.
Při každém běhu se lingo/translations znovu sestaví z commitu výchozí větve, na kterém běh probíhal, a vynuceně se odešle. Otevřená žádost o sloučení tak zobrazuje nejnovější rozdíl v překladech. Ruční úpravy v této větvi další běh přepíše, proto je provádějte až po sloučení. Dokud žádost o sloučení nesloučíte, ve výchozí větvi zůstává předchozí .lingo/lock.json a další běh znovu odešle stejné změny zdroje. Pokud pozdější commity vrátí zpět všechny změny zdroje přeložené v žádosti o sloučení, další běh nenajde nic k odeslání a nechá žádost otevřenou s neaktuálními překlady. V takovém případě ji místo sloučení zavřete.
Označte žádosti o sloučení s neaktuálními překlady jako neúspěšné #
lingo check porovnává každý nastavený zdroj s .lingo/lock.json a vyžaduje přítomnost všech cílových souborů. Skončí se stavovým kódem 1, pokud se zdroj od posledního překladu změnil, nemá záznam v souboru Lockfile, chybí cílový soubor nebo žádný zdrojový soubor neodpovídá vzorům files. Nepotřebuje klíč API ani proměnnou CI/CD a nic nezapisuje, takže může běžet i pro žádosti o sloučení z forků. Kromě telemetrie CLI, kterou DO_NOT_TRACK=1 vypíná, neprovádí žádná síťová volání. Příklady s npx ale před spuštěním kontroly stále stahují CLI z npm. Nahrazuje kontrolu --frozen z předchozí verze CLI.
Kontroluje soubory, nikoli klíče: ručně upravený cílový soubor kontrolou projde a chybějící klíč v existujícím cílovém souboru se nehlásí, s výjimkou katalogů React .jsonc. Bez .lingo/lock.json nedokáže rozpoznat změny zdroje, takže změněný nebo dosud neodeslaný zdroj nezpůsobí selhání kontroly. Kontrola na to upozorní na stderr. Zahrňte do commitu soubor Lockfile, který zapisuje lingo push.
Přidejte check do seznamu stages a poté přidejte úlohu odpovídající vašemu nastavení. Pokud vývojáři spouštějí lingo push --wait a ukládají výsledek do commitu společně se změnou zdroje, kontrolujte každou žádost o sloučení:
check_translations:
stage: check
image: node:22
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
script:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 checkPři použití úlohy pro výchozí větev kontrolujte pouze žádost o sloučení překladů, kterou tato úloha vytvoří. Žádosti o sloučení nových funkcí totiž mění zdroje ještě před překladem:
check_translations:
stage: check
image: node:22
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME == "lingo/translations"'
script:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 checkTato kontrola se hodí pro nastavení, ve kterém se překlady ukládají do commitu společně se změnou zdroje:
| Kde probíhá překlad | Kontrola u každé žádosti o sloučení |
|---|---|
Vývojáři spustí lingo push --wait a před otevřením žádosti o sloučení uloží výsledek do commitu | Ano. Žádost o sloučení neprojde, pokud se zdroj změnil bez překladu. |
| Úloha pro žádost o sloučení ukládá commity do zdrojové větve | Ne. Kontrola by prověřovala commit před překladem a odeslání změn touto úlohou nespustí novou pipeline. |
| Úloha pro výchozí větev otevírá žádost o sloučení překladů | Pouze pro lingo/translations, s druhou výše uvedenou úlohou. Žádosti o sloučení nových funkcí ze své podstaty mění zdroje ještě před překladem. |
Hashe zdrojů závisí na přesné podobě každého bajtu. Zajistěte, aby checkout, ve kterém běžel lingo push, a checkout v CI používaly stejné konce řádků, například pomocí * text=auto eol=lf v .gitattributes.
Zajistěte předvídatelný průběh opakovaných úloh #
Omezte automatické úlohy na zamýšlené důvěryhodné větve a zdrojové cesty. Pokud používáte spouštěče žádostí o sloučení, omezte také zdrojový projekt a cílovou větev. Vhodným pravidlem pro větev nebo zásadou pro vynechání CI spolu s ukončením při prázdném rozdílu zabraňte tomu, aby generované commity opakovaně odesílaly práci k překladu.
V monorepu přejděte do balíčku s požadovanou konfigurací a uchovávejte jeho výstup i stav v cestách relativních k tomuto balíčku. Nezávislé balíčky mohou používat různé lokalizační engine a jazyky; jejich soubory Lockfile uchovávejte odděleně. Stejný postup s runnerem funguje i s GitLab ve vlastní správě, pokud to umožňují síťový přístup, nástroje runneru, proměnné a zásady repozitáře.
Běžný přírůstkový překlad může zachovat ručně upravený cílový klíč, dokud se jeho zdroj nezmění. Změna zdroje může vést k opětovnému vygenerování tohoto klíče. Doplnění chybějících souborů a vynucené opětovné generování mají odlišný rozsah. Bez vzorů souborů zahrnuje --force všechny nakonfigurované zdrojové a cílové jazyky a může nahradit schválené překlady. Zadávejte vzory výslovně a před vynuceným spuštěním zkontrolujte odhad. Při změně příkazu pro odesílání si prostudujte Push.
Obnovte provoz pipeline nebo ji vyřaďte #
Podle chyby zvolte další krok: opravte instalaci balíčků, zpřístupněte proměnnou s potřebným oprávněním, dokončete kontrolu, vyřešte konflikt při slučování nebo po odstranění příčiny zopakujte neúspěšné zpracování cílových souborů. Zachovejte úspěšné artefakty, ale částečně dokončené vydání ponechte zřetelně označené jako nedokončené.
Vypnutím spouštěče zabráníte spouštění nových pipeline. Při rušení runneru samostatně zkontrolujte veškerou práci, která už byla odeslána k překladu. Až tento postup přestanete používat, odstraňte již nepotřebné přihlašovací údaje k API a repozitáři.