Postup pro Bitbucket Pipelines

Spouštějte překlad souborů v Bitbucket Pipelines, commitujte výsledky zpět a zablokujte pull requesty s neaktuálními překlady.

Pomocí pipeline ve službě Bitbucket přeložte zdrojové soubory vybrané v konfiguraci Lingo.dev. CLI odešle úlohu a stáhne cílové soubory; vaše pipeline určuje, jak je uchovat a doručit. Tento postup začíná vlastní, ručně spouštěnou pipeline, abyste mohli zkontrolovat jeden překlad, než naplánujete pravidelné zpracování.

Připojení zajišťuje volání API z vašeho runneru, nikoli nativní konektor k účtu Bitbucket. Zápis do repozitáře a vytváření pull requestů vyžadují samostatná oprávnění ve službě Bitbucket.

Připravte jeden funkční katalog #

Na svém počítači projděte průvodce rychlým startem s CLI a poté do commitu zahrňte .lingo/config.json, zkontrolované cílové soubory a .lingo/lock.json. Do této konfigurace patří zdrojové a cílové jazyky, lokalizační engine a vzory pro výběr souborů.

Příklad používá locales/en.json a jako jediný cíl existující soubor ve španělštině na cestě locales/es.json. 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, uveďte cesty ke všem cílům. Lockfile zaznamená zdroj jako přeložený, takže ho pozdější příkaz push přeskočí a cíl, který není součástí artefaktu, zůstane neaktuální. Než začnete pravidelně používat níže uvedený příkaz pro zpracování změn zdroje, vytvořte chybějící cílové soubory pomocí lingo push --backfill-missing --wait. Běžný příkaz push zpracuje následné úpravy zdroje; doplnění chybějících souborů ale nedoplní chybějící klíče v existujícím cíli.

Uložte LINGO_API_KEY jako zabezpečenou proměnnou repozitáře. CLI načítá pouze proměnnou s tímto názvem; proměnnou LINGODOTDEV_API_KEY z předchozího CLI ignoruje, proto ji přejmenujte. Spouštějte pipeline pouze nad důvěryhodným kódem a při práci s přihlašovacími údaji nechte trasování shellu vypnuté. Ani zabezpečenou proměnnou není bezpečné zpřístupňovat libovolným skriptům z pull requestu.

Příklady používají pevně nastavenou verzi CLI 1.21.0. lingo check kontroluje soubory s překlady od verze CLI 1.20.0. Pokud chcete verzi spravovat pomocí závislostí projektu a souboru Lockfile, postupujte podle průvodce nastavením CI.

Přeložte soubory a uchovejte výsledek #

Do bitbucket-pipelines.yml přidejte tuto vlastní pipeline:

yaml
image: node:22

pipelines:
  custom:
    translate-catalog:
      - step:
          name: Translate and inspect
          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:
            - locales/es.json
            - .lingo/lock.json

Ověřte, že runner může stáhnout CLI z npm. Cesty k souborům přizpůsobte své konfiguraci.

Ověřte ID organizace a engine v souboru .lingo/config.json zahrnutém v commitu. Vytvořte commit s jednou drobnou úpravou anglického zdroje a na této důvěryhodné větvi spusťte translate-catalog. Zkontrolujte výsledek spuštění a rozdíly, poté stáhněte artefakt a porovnejte změněnou španělskou položku s příslušnou revizí zdroje. Načtěte katalog v aplikaci a ověřte proměnné i vykreslení.

Kontrola existence souborů a parsování JSON odhalí chybějící nebo nesprávně formátovaný výstup. Nerozliší však starý platný soubor od nového překladu, o který jste požádali. Pokud lokalizační engine vyžaduje lidskou kontrolu, dokončete ji a stáhněte hotový výstup, než artefakt přijmete.

Uchovejte stav odeslání a načtení #

Push je ve výchozím nastavení asynchronní. push --wait počká na dokončení běhu a zapíše přeložené soubory do checkout. Bez --wait příkaz lingo push pouze odešle požadavek na spuštění a skončí, takže následující příkaz nenajde žádné nové soubory k uchování ani commitování. Pokud se čeká na lidskou kontrolu, může být i tak nutné výsledky načíst v pozdějším kroku.

Před čekáním na kontrolu nebo samostatným krokem načtení zařaďte postup pro uchování stavu spuštění CI. Po odeslání exportujte konkrétní ukazatel a původní absolutní cestu ke kořenovému adresáři projektu, a to i v případě, že následná validace selže. Uchovejte .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, cílový soubor a soubor Lockfile jako artefakty s omezeným přístupem a s dobou uchování dostatečně dlouhou pro kontrolu. Zajistěte, aby původní selhání kroku zůstalo viditelné, a nikdy nearchivujte celý obsah ~/.lingo ani přihlašovací údaje.

Pro načtení obnovte stejnou revizi a uchovaný stav souborů v kořenovém adresáři na zaznamenané absolutní cestě. Obnovte pouze daný ukazatel, přihlašovací údaje poskytněte zvlášť a před shromážděním výstupu použijte Pull s --dry-run. Pokud pozdější krok pipeline nedokáže tuto cestu znovu vytvořit, použijte pro odeslání i načtení trvalý autorizovaný runner. Konflikty v lokálním výstupu řešte uvážlivě; vynucený pull může zahodit změny provedené při kontrole.

Zvolte způsob doručení výstupu do repozitáře #

Artefakt postačí, pokud má výstup před doručením zkontrolovat člověk nebo pozdější úloha vydání. Přeložené soubory a soubor Lockfile ze stejné dokončené operace uchovávejte společně.

Pokud má aktualizace repozitáře projít kontrolou, odešlete změny do překladové větve a poté otevřete pull request v Bitbucket nebo prostřednictvím jeho zdokumentovaného API. Krok může odesílat změny do vlastního repozitáře přes výchozí origin bez dalších přihlašovacích údajů, jak ukazuje následující část. SSH klíč repozitáře nebo přístupový token přidejte pouze tehdy, když odeslání blokují oprávnění větve, nebo pokud chcete vytvořit pull request přes API, k čemuž je potřeba oprávnění k zápisu pull requestů. Nastavte identitu týmového bota, k commitu připravujte pouze známé cílové cesty a .lingo/lock.json a krok ukončete, pokud je rozdíl připravených změn prázdný. Používejte různé názvy větví nebo stejné větve znovu používejte jen záměrně, aby si souběžné běhy navzájem nepřepisovaly výsledky.

Přímý commit používá stejné kontroly výstupu a stejně omezený výběr souborů pro commit, změny ale odesílá do výslovně určené důvěryhodné větve. Přímé doručení do výchozí větve vynechává kontrolu překladového pull requestu, proto musí jít o vědomou volbu v rámci pravidel pro větve. V obou případech zkontrolujte výsledný výstup aplikace.

Klíč API Lingo.dev uchovávejte odděleně od přihlašovacích údajů k repozitáři. Patří do prostředí překladového procesu, nikdy do adresy vzdáleného repozitáře Git, souboru zahrnutého v commitu ani výstupního artefaktu. Místo git add . připravujte k commitu konkrétní cesty, abyste nepřidali nesouvisející soubory runneru.

Commitování překladů zpět do větve #

Tato pipeline pro větev přeloží každou změnu, která se dostane do main, a commituje výsledek do main. Předpokládá, že počáteční doplnění překladů je už commitované a lidská kontrola v engine je vypnutá, takže se překlad dokončí v jediném kroku. Přidejte její sekci branches pod stejný klíč pipelines jako vlastní pipeline. Celý soubor pak vypadá takto:

yaml
image: node:22

pipelines:
  custom:
    translate-catalog:
      - step:
          name: Translate and inspect
          script:
            - 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:
            - locales/es.json
            - .lingo/lock.json
  branches:
    main:
      - step:
          name: Translate and commit
          auth:
            system:
              scopes:
                - read:git:bitbucket
                - write:git:bitbucket
          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 "[skip ci] Update translations"
            - git push origin "HEAD:$BITBUCKET_BRANCH"

lingo push --wait při selhání některého cíle skončí s nenulovým návratovým kódem, takže se krok zastaví ještě před commitem. Pokud se nic nezměnilo, vypíše "Nothing to push", rozdíl připravených změn je prázdný a krok skončí bez commitu.

Pipelines nastavuje vzdálený repozitář origin, aby krok mohl odesílat změny zpět do vlastního repozitáře bez dalších přihlašovacích údajů. Blok auth daného kroku uděluje jeho vestavěnému tokenu oprávnění k odesílání změn příkazem Git push. Od 30. dubna 2027 už Bitbucket toto oprávnění krokům bez bloku auth neuděluje. Runnery provozované na vlastní infrastruktuře vyžadují pro použití auth verzi 6.1.0 nebo novější. Pokud odeslání změn blokuje omezení větve main, přidejte main jako zdrojovou větev v nastavení oprávnění k zápisu pro Pipelines u tohoto omezení. Případně kroku poskytněte klíč SSH nebo přístupový token s oprávněním k zápisu podle průvodce Bitbucket pro odesílání změn zpět do repozitáře.

Krok se nezacyklí. [skip ci] ve zprávě commitu zabrání tomu, aby Bitbucket spustil pipeline pro commit s překlady. Bez něj by další běh nenašel nic k odeslání, protože commitovaný soubor .lingo/lock.json už zaznamenává nový stav zdroje. Pokud se větev během překladu posune, Git odeslání odmítne; novější commit přeloží jeho vlastní pipeline.

Přizpůsobte spouštěče a cesty k balíčkům #

Automatické spouštěče pro větve nebo pull requesty přidávejte až poté, co rozhodnete, který zdrojový kód smí přistupovat k přihlašovacím údajům a do které větve lze zapisovat. Fork nemusí mít k dispozici tajné údaje ani cíl umožňující zápis; neřešte to spouštěním jeho nedůvěryhodného kódu s privilegovanými přihlašovacími údaji.

Vygenerované commity by neměly spouštět překlad donekonečna. Vyberte relevantní zdrojové cesty a důvěryhodné větve, použijte vhodné pravidlo pro vygenerované commity a zachovejte ukončení v případě, že nejsou žádné změny. Pokud se zdroj nezměnil, je v pořádku, že nevzniknou žádné rozdíly.

Pokud je konfigurace na cestě apps/web/.lingo/config.json, spouštějte CLI z apps/web. Cesty k artefaktům pipeline se i nadále řídí pravidly služby Bitbucket pro cesty relativní ke kořenu repozitáře, proto používejte cesty jako apps/web/locales/es.json a apps/web/.lingo/lock.json. Změna pracovního adresáře CLI nemění pravidla pro cesty k artefaktům.

Zablokování pull requestů s neaktuálními překlady #

lingo check porovnává každý nakonfigurovaný zdroj s .lingo/lock.json a vyžaduje přítomnost všech cílových souborů. Skončí s návratovým kódem 1, pokud se zdroj od posledního překladu změnil, nemá záznam v Lockfile, chybí cílový soubor nebo žádný zdrojový soubor neodpovídá vzorům files. Nepotřebuje klíč API ani proměnnou repozitáře a nic nezapisuje. Kromě telemetrie CLI, kterou DO_NOT_TRACK=1 vypíná, neprovádí žádná síťová volání; v příkladu npx se však před spuštěním kontroly stále stahuje CLI z npm. Nahrazuje kontrolní podmínku --frozen z předchozího 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 zjistit změny zdroje, takže změněný zdroj ani zdroj, který dosud nebyl odeslán příkazem push, nezpůsobí selhání kontroly. Na tuto skutečnost upozorní na stderr. Zahrňte do commitu Lockfile, který zapisuje lingo push.

Tato kontrola je určena pro nastavení bez výše uvedené pipeline pro větev; důvod vysvětluje následující tabulka. Přidejte sekci pull-requests pod pipelines, vedle custom, pokud si ponecháte ručně spouštěnou pipeline. Samostatně vypadá soubor takto:

yaml
image: node:22

pipelines:
  pull-requests:
    "**":
      - step:
          name: Check translations
          script:
            # lingo check needs CLI 1.20.0 or newer.
            - npx -y @lingo.dev/cli@1.21.0 check

Kontrola se hodí pro nastavení, ve kterém se překlady commitují společně se změnou zdroje:

Kde probíhá překladKontrola každého pull requestu
Vývojáři spustí lingo push --wait a commitují výsledek před otevřením pull requestuAno. Kontrola selže u pull requestu, jehož zdroj se změnil bez aktualizace překladu.
Pipeline pro větev commituje do main po sloučeníNe. Pull requesty s novými funkcemi v tomto postupu záměrně mění zdroje ještě před překladem.

Hashe zdrojů závisejí na přesné shodě bajtů. Zajistěte, aby checkout, ve kterém se spustil lingo push, a checkout v CI používaly stejné konce řádků, například pomocí * text=auto eol=lf v .gitattributes. Zachovejte také kontroly souborů prostředků aplikace.

Obnovte chybějící výstup nebo zastavte práci #

Pokud výstup chybí, zkontrolujte vybrané zdrojové soubory, výchozí stav, pokrytí cílových jazyků, dostupnost zabezpečených proměnných, stav kontroly a hlášená selhání. Než se rozhodnete úlohu odeslat znovu, obnovte zaznamenané spuštění. Před doplněním chybějících cílových souborů v existujícím projektu dokončete, načtěte a zkontrolujte běžné aktualizace stávajících cílových souborů. Po celou dobu doplňování pak ponechte zdrojovou revizi beze změny. Postupujte podle části Přidání jazyka. Vynucené opětovné generování používejte pouze tehdy, když skutečně chcete nahradit vybraný přijatý text; část obnovení po neúspěšném spuštění vysvětluje, jak požádat o další pokus bez vynuceného nahrazení.

Chcete-li zastavit nové úlohy, vypněte spouštěč pipeline. Při rušení běhu runneru samostatně zkontrolujte všechna spuštění, která už byla odeslána na server. Až tento postup přestanete používat, odeberte nepoužívané proměnné API a oprávnění k zápisu u poskytovatele.