Postup pro CI v GitHub Actions

Spusťte překlad v důvěryhodné úloze GitHub Actions, zkontrolujte její artefakty a až bude výstup připravený, přidejte doručení formou pull requestu.

Spouštějte Lingo.dev CLI v GitHub Actions, pokud má překlad využívat spouštěče a kontroly vaší stávající pipeline. Runner načte konfiguraci repozitáře, odešle změny zdrojového obsahu a stáhne přeložené soubory. Sami určíte, zda soubory zůstanou uložené jako artefakty, nebo se z nich vytvoří pull request.

Tento postup začíná ručním spuštěním a přístupem k repozitáři pouze pro čtení. Po kontrole jedné změněné zprávy můžete přidat oprávnění k zápisu potřebná k vytvoření pull requestu s překlady. Alternativou je nativní GitHub App, která zajišťuje spravované zpracování repozitáře bez tohoto postupu s runnerem.

Připravte repozitář #

Projděte si lokálně rychlý úvod do CLI s jedním zdrojovým souborem a jedním cílovým jazykem. Do commitu zahrňte .lingo/config.json, zkontrolovaný cílový soubor a .lingo/lock.json. Konfigurace určuje lokalizační engine, zdrojový i cílové jazyky a vzory souborů. Lockfile zaznamenává výchozí stav pro další změny zdrojového obsahu.

Pro následující příklad nastavte locales/en.json jako zdroj a španělštinu jako cílový jazyk. Výsledkem bude locales/es.json. První chybějící cílový soubor vytvoříte pomocí lingo push --backfill-missing --wait; při dalších úpravách zdrojového obsahu použijte lingo push --wait. Zpětné doplnění vybírá chybějící cílové soubory, nedoplňuje tedy chybějící klíče v existujícím souboru.

Přidejte LINGO_API_KEY mezi tajné údaje Actions v repozitáři nebo prostředí. Tento údaj poskytuje přístup k Lingo.dev nezávisle na oprávněních k repozitáři na GitHubu. Úlohu s přihlašovacími údaji spouštějte pouze nad důvěryhodným kódem. Zejména nepoužívejte pull_request_target k načtení a spuštění nedůvěryhodné koncové revize pull requestu s přístupem k tajnému údaji.

Příklad používá pevně danou verzi CLI. Pokud ji chcete spravovat prostřednictvím závislostí projektu a souboru Lockfile, postupujte podle průvodce nastavením CI.

Získejte artefakt s překladem #

Uložte tento obsah jako .github/workflows/translate.yml. Příklad používá Node.js 22.

yaml
name: Translate catalog
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Translate and download
        # Replace 1.21.0 with the current CLI version.
        run: npx -y @lingo.dev/cli@1.21.0 push --wait
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Inspect expected output
        run: |
          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
      - uses: actions/upload-artifact@v4
        with:
          name: translated-catalog
          include-hidden-files: true
          path: |
            locales/es.json
            .lingo/lock.json

Ověřte ID organizace a engine v souboru .lingo/config.json uloženém v commitu. Proveďte jednu úpravu anglického zdrojového obsahu, vytvořte commit a spusťte workflow z této důvěryhodné větve. V logu úlohy zkontrolujte výsledek běhu a přehled změn. Poté stáhněte artefakt a najděte španělskou položku odpovídající vaší úpravě. Načtěte ji v aplikaci a zkontrolujte její význam i proměnné.

Nahrávání zahrnuje i skryté soubory, aby se zachoval .lingo/lock.json. Seznam cest omezte na požadovaný cílový soubor a Lockfile; nepřidávejte do něj přihlašovací údaje ani jiné soukromé skryté soubory.

Kontroly v shellu ověřují přítomnost souborů a syntaxi JSON. Oběma může projít i starý cílový soubor, proto je důležité zkontrolovat změněnou položku. Pokud lokalizační engine vyžaduje lidskou kontrolu, může běh i po skončení příkazu stále čekat na člověka. Než takové pravidlo použijete na jednorázovém runneru, přidejte postup pro zachování stavu běhu v CI. Po odeslání exportujte ukazatel na konkrétní běh a původní absolutní cestu ke kořenovému adresáři projektu. Nahrajte .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, cílový soubor a Lockfile jako artefakty s omezeným přístupem. V krocích exportu a nahrávání použijte if: always(), aby pozdější selhání kontroly nezpůsobilo ztrátu stavu potřebného k obnově. Pokud ukazatel chybí, je nutné prověřit odeslání, nikoli si ukazatel vymyslet.

Po kontrole obnovte přesně tutéž revizi a stav souborů na zaznamenané absolutní cestě ke kořenovému adresáři. Obnovte ukazatel, samostatně proveďte ověření totožnosti a použijte stažení s kontrolou konfliktů. Pokud jiný runner nedokáže tuto cestu znovu vytvořit, proveďte odeslání i stažení na trvalém runneru s potřebným oprávněním. Starý cílový soubor z prvního artefaktu nepovažujte za dokončený překlad.

push --wait počká a stáhne dostupný dokončený výstup. Bez --wait příkaz push obvykle skončí hned po odeslání. Oddělené úlohy pro odeslání a stažení vyžadují stejný export a obnovení stavu běhu; samotné zkopírování souboru Lockfile nestačí. Stažené cílové soubory a Lockfile ze stejné dokončené operace uchovávejte pohromadě a nikdy nearchivujte celý obsah ~/.lingo.

Doručte překlad formou pull requestu #

Po úspěšné kontrole artefaktu udělte úloze oprávnění contents: write a pull-requests: write. Zásady repozitáře musí také umožňovat vytváření pull requestů prostřednictvím Actions. GITHUB_TOKEN slouží k autorizaci těchto operací na GitHubu; pro překlad ponechte LINGO_API_KEY.

Nastavte identitu pro Git podle týmových zásad pro boty. Poté za ověření výstupu přidejte krok, který připraví k commitu pouze očekávaný cílový soubor a Lockfile:

bash
git add locales/es.json .lingo/lock.json
git diff --cached --quiet && exit 0
branch="lingo/translations-${GITHUB_RUN_ID}"
git switch -c "$branch"
git commit -m "chore: update translations"
git push origin "$branch"
gh pr create --fill --base "$GITHUB_REF_NAME" --head "$branch"

Runnery hostované na GitHubu obsahují GitHub CLI. Tomuto kroku předejte GH_TOKEN z secrets.GITHUB_TOKEN. Postup předpokládá ruční spuštění z důvěryhodné větve a nový název větve. Při opakovaném spuštění s existující větví musíte výslovně rozhodnout, zda ji znovu použijete, nebo nahradíte. Nejde o workflow pro zápis zpět do forku.

Pull request cílí na větev, ze které jste úlohu spustili. Pokud GitHub označí jeho workflow jako čekající na schválení, musí uživatel s oprávněním k zápisu do repozitáře zvolit Schválit spuštění workflow; viz chování GITHUB_TOKEN na GitHubu. Před sloučením zkontrolujte změny v překladech, výsledky kontrol a výstup aplikace.

Pokud to zásady pro větve umožňují, lze vytvářet commity i přímo ve větvi, která běh spustila. Tím ale odpadá tento samostatný krok kontroly obsahu a je nutné zabránit smyčkám.

Naplánujte práci a zpracujte monorepozitáře #

Jakmile první běh přinese užitečný výsledek, přidejte spouštění při odeslání změn do důvěryhodných větví a filtry cest ke zdrojovým souborům. Vygenerované commity s překlady nesmí stále dokola spouštět další překladovou úlohu. Zkombinujte vhodné filtry větví nebo cest s ukončením při nezjištění změn v kroku doručení.

V monorepozitáři nastavte jako pracovní adresář kroku překladu balíček, který obsahuje .lingo/config.json. Upravte cesty k artefaktům a souborům připraveným ke commitu tak, aby zahrnovaly i tento balíček. Matice může zpracovávat nezávislé balíčky, dvě její položky by ale neměly souběžně aktualizovat stejnou konfiguraci a Lockfile. Položky v rámci jednoho spuštění sdílejí ID tohoto spuštění, proto každé přidělte vlastní název artefaktu a vlastní větev pro překlady, například přidáním názvu balíčku do translated-catalog a lingo/translations-${GITHUB_RUN_ID}.

Obnovte nedokončený běh #

Vycházejte z nahlášeného stavu: u neúspěšných cílů je třeba vyřešit chybu, u cílů čekajících na kontrolu je nutné rozhodnout a při lokálních konfliktech během stahování musíte vybrat mezi ruční úpravou a staženým výsledkem. Úspěšný výstup ponechte dostupný ke kontrole a nedokončené jazyky nechte jako nevyřešené. Částečný výsledek nesmí být považován za kompletní vydání pro daný jazyk.

Nenulové návratové kódy neskrývejte. || true, vynucené stažení přepisující úpravy nebo vynucené zpracování všech cílů může skrýt příčinu a přepsat již přijatou práci. Průvodce workflow v CI vysvětluje, jak při obnově zachovat revizi a výchozí stav.

Chcete-li zastavit spouštění nových úloh na runneru, zakažte workflow nebo jeho spouštěč. Pokud už úloha odeslala překlad, při rušení Actions samostatně zkontrolujte příslušný běh na serveru. Při vyřazení workflow odeberte nepoužívané tajné údaje a oprávnění k zápisu do repozitáře.