Postup pro Buildkite
Překládejte soubory v pipeline Buildkite, odesílejte výsledky zpět do větve a nastavte selhání kontroly pull requestů s neaktuálními překlady.
Krok v Buildkite může pomocí Lingo.dev CLI překládat soubory repozitáře na vašich vlastních agentech. CLI odešle zdrojové soubory vybrané konfigurací Lingo.dev a zapíše překlady do checkout; o způsobu jejich doručení rozhoduje vaše pipeline. Buildkite spravuje agenty, tajné údaje a přístup k repozitáři; Lingo.dev zpracovává soubory prostřednictvím lokalizačního engine.
Jde o postup pro CI, nikoli o nativní připojení k Buildkite. Začněte jedním překladovým krokem na výchozí větvi nebo při sestavování pull requestů a zkontrolujte jeho první commit. Kontrolu pull requestů přidejte jen tam, kde je podle příslušné tabulky vhodná.
Připravte repozitář a agenta #
Projděte lokálně rychlý start s CLI. Do commitu zahrňte .lingo/config.json, schválené cílové soubory a .lingo/lock.json. Konfigurace určuje zdrojový jazyk, cílové jazyky, vzory pro výběr souborů a lokalizační engine. Příklady používají locales/en.json jako zdroj a existující španělský cílový soubor 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, vypište všechny cílové cesty, nebo připravte k commitu celý cílový adresář, například locales/. Lockfile zaznamená zdroj jako přeložený, takže se při pozdějším odeslání přeskočí a cílový soubor vynechaný z commitu zůstane neaktuální.
Než zavedete pravidelně spouštěný krok, vytvořte chybějící cílové soubory pomocí lingo push --backfill-missing --wait. Při dalších úpravách zdroje používejte běžný příkaz lingo push --wait. Doplnění chybějících souborů nedoplní chybějící klíče v existujícím cílovém souboru.
Agent potřebuje Node.js, npm a Git a také síťový přístup k registru npm a službě Lingo.dev. Přihlašovací údaj, který agent používá pro checkout repozitáře, například nasazovací klíč, musí umožňovat i odesílání změn do větve, do které krok zapisuje.
Uložte klíč API Lingo.dev jako tajný údaj Buildkite s názvem LINGO_API_KEY. CLI čte pouze tento název; proměnnou LINGODOTDEV_API_KEY z předchozího CLI ignoruje, proto ji přejmenujte. Tajný údaj načítejte pouze v kroku, který překládá. Klíč secrets: v tomto kroku vyžaduje agenta Buildkite verze 3.106.0 nebo novější, spuštěného v clusteru, kde je tajný údaj uložený; se staršími agenty pipeline selže. U starších agentů nebo agentů mimo cluster odstraňte secrets: a místo toho pro daný krok exportujte LINGO_API_KEY z hooku environment agenta nebo z pluginu pro správu tajných údajů.
V nastavení GitHubu pro danou pipeline ponechte vypnutou možnost Povolit sestavení z forkovaných repozitářů třetích stran. Pull request z forku se sestavuje podle souboru pipeline.yml ze samotného forku. Ten může přidat krok, který načte tajný údaj, a žádná podmínka if: ve vašem souboru tomu nezabrání. K tajnému údaji přidejte také zásadu přístupu, aby jej mohla číst pouze sestavení této pipeline.
Příklady používají pevně nastavenou verzi CLI 1.21.0. Příkaz lingo check kontroluje překladové soubory od verze CLI 1.20.0. Chcete-li verzi spravovat prostřednictvím závislostí projektu a souboru Lockfile, postupujte podle průvodce nastavením CI.
Překládejte a odesílejte výsledky zpět do větve #
Tento krok přeloží každou změnu, která se dostane do výchozí větve, a odešle výsledek do stejné větve. Předpokládá, že úvodní doplnění překladů už je součástí commitu a v engine je vypnutá možnost Lidská kontrola, takže překlad proběhne v jediném kroku. Přidejte jej do .buildkite/pipeline.yml:
steps:
- label: "Translate"
if: build.branch == pipeline.default_branch && build.pull_request.id == null
concurrency: 1
concurrency_group: "lingo-translations"
# secrets: needs Buildkite agent 3.106.0 or later.
secrets:
- LINGO_API_KEY
command: |
# 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:refs/heads/$${BUILDKITE_BRANCH}"--wait zajistí, že krok počká na dokončení běhu a zapíše přeložené soubory do checkout. Bez něj lingo push pouze odešle běh ke zpracování a skončí, takže krok nenajde nic k commitu. Pokud zpracování některého cíle selže, lingo push --wait skončí s nenulovým návratovým kódem a krok se zastaví před commitem. Pokud se nic nezměnilo, vypíše „Není co odeslat“, mezi změnami připravenými k commitu nejsou žádné rozdíly a krok skončí bez commitu.
Buildkite provádí checkout konkrétního commitu, nikoli větve, proto příkaz pro odeslání výslovně uvádí větev. $$ ponechá BUILDKITE_BRANCH k rozvinutí shellem při spuštění kroku; s jediným $ by Buildkite zapsal název větve do textu příkazu už při nahrávání pipeline. concurrency a concurrency_group zajistí, že v jednu chvíli běží jen jeden překlad. Pokud do větve během překladu přibyl další commit, Git odeslání odmítne; překlad provede sestavení pro novější commit.
Krok se nezacyklí. Buildkite přeskakuje sestavení pro commity, jejichž zpráva obsahuje [skip ci]. Bez toho by další sestavení nenašlo nic k odeslání, protože soubor .lingo/lock.json uložený v commitu už nový zdroj zaznamenává.
Přímým odesíláním do výchozí větve se vynechává kontrola překladového pull requestu, proto tuto možnost zvolte vědomě v rámci pravidel pro větve. Chcete-li překlady nejprve zkontrolovat, odesílejte je do samostatné větve, například lingo/translations, a otevřete pull request pomocí nástrojů svého poskytovatele Gitu.
Překládejte při sestavování pull requestů #
Chcete-li změny zdroje v každém pull requestu překládat na jeho vlastní větvi, použijte tento krok místo kroku pro výchozí větev. Platí pro něj stejné předpoklady. Jeho podmínka if: přeskakuje pull requesty z forků, protože krok nemůže odesílat změny do větve forku.
Krok vyžaduje dvě nastavení v nastavení GitHubu pro danou pipeline. Zapněte Sestavit při otevření nebo aktualizaci pull requestu. Vypněte Sestavovat větve nebo tuto možnost omezte na výchozí větev. Při zapnutém sestavování větví může odeslání změn do větve pull requestu spustit sestavení bez údajů o pull requestu. Krok takové sestavení přeskočí, takže se nic nepřeloží a nic neselže.
if: nechrání LINGO_API_KEY. Buildkite tuto podmínku čte ze souboru pipeline.yml samotného pull requestu a fork může tento soubor změnit. Sestavování forků proto musí zůstat vypnuté, jak uvádí část o nastavení. Soubor může změnit i pull request z větve v repozitáři, takže kdokoli s právem odesílat změny do větve může prostřednictvím tohoto kroku klíč přečíst. Krok používejte jen tam, kde smí mít klíč každý s právem odesílat změny.
steps:
- label: "Translate pull request"
if: build.pull_request.id != null && build.pull_request.repository.fork != true
# secrets: needs Buildkite agent 3.106.0 or later.
secrets:
- LINGO_API_KEY
command: |
# 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 origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"Zpráva commitu záměrně neobsahuje [skip ci]. Buildkite sestaví překladový commit, krok se spustí znovu, nenajde nic k odeslání a skončí bez commitu. Cyklus tak skončí po jednom dodatečném sestavení. Toto sestavení přiřadí stav nejnovějšímu commitu pull requestu. S [skip ci] by se pro nejnovější commit žádné sestavení Buildkite nespustilo a povinná kontrola stavu Buildkite by zablokovala sloučení.
Přihlašovací údaj agenta pro checkout musí umožňovat odesílání změn do větví pull requestů. Pokud do větve během překladu přibyl další commit, Git odeslání odmítne a krok selže; překlad provede sestavení pro novější commit. Dvě rychlá odeslání tedy spustí dva překlady a oba se účtují. V nastavení pipeline zapněte Rušit mezilehlá sestavení, aby novější odeslání zrušilo starší sestavení. Překlad, který starší sestavení už odeslalo ke zpracování, se nezruší.
Nastavte selhání kontroly 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, zdroj nemá záznam v souboru Lockfile, chybí cílový soubor nebo žádný zdrojový soubor neodpovídá vzorům files. Nepotřebuje klíč API ani tajný údaj a nic nezapisuje. Kromě telemetrie CLI, kterou vypíná DO_NOT_TRACK=1, neprovádí žádná síťová volání; příklad s npx ale 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 příkaz nevidí změny zdroje, takže změněný nebo dosud neodeslaný zdroj nezpůsobí selhání kontroly. Na tuto skutečnost upozorní na stderr. Do commitu zahrňte soubor Lockfile, který zapisuje lingo push.
Přidejte tento krok do .buildkite/pipeline.yml, pokud je podle tabulky níže tato kontrola vhodná. Patří do konfigurace, která nepoužívá ani jeden ze dvou výše uvedených překladových kroků. Každý zdejší příklad proto představuje úplný seznam steps: pro jednu konfiguraci; začleňte jeho krok do stávajícího seznamu steps:, místo abyste přidávali druhý klíč steps::
steps:
- label: "Check translations"
if: build.pull_request.id != null
command:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 checkKontrola je vhodná pro konfiguraci, ve které se překlady ukládají do commitu společně se změnou zdroje:
| Kde probíhá překlad | Kontrola u každého pull requestu |
|---|---|
Vývojáři spustí lingo push --wait a před otevřením pull requestu uloží výsledek do commitu | Ano. Kontrola selže u pull requestu, jehož zdroj se změnil bez překladu. |
| Překladový krok odešle změny do výchozí větve po sloučení | Ne. Pull requesty pro nové funkce v tomto nastavení záměrně mění zdroje ještě před překladem. |
| Krok pro pull requesty ukládá překlady do commitu ve větvi pull requestu | Ne. V sestavení, které překládá, kontrola vidí commit před překladem a selže. Opakované spuštění samotného kroku nad překladovým commitem, při kterém už není co odeslat, ukazuje, že se od .lingo/lock.json žádný zdroj nezměnil. |
Hashe zdrojů závisejí 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.
Přizpůsobte krok #
V monorepu spouštějte CLI z balíčku, který obsahuje .lingo/config.json, například pomocí cd apps/web na začátku příkazu, a připravte k commitu cílové soubory a soubor Lockfile tohoto balíčku. Nezávislé balíčky mají samostatné soubory Lockfile a mohou používat různé lokalizační engine.
Pokud lokalizační engine odesílá práci k lidské kontrole, lingo push --wait zapíše pouze dokončené soubory a skončí s návratovým kódem 0. Neukládejte tento částečný výsledek do commitu jako úplný. Doplňte postup pro zachování stavu běhu v CI a po dokončení kontroly načtěte zbytek pomocí Stažení na stejném agentovi.
Obnovte provoz a vyřaďte krok #
Podle chyby zvolte další postup: opravte instalaci balíčků, doplňte tajný údaj, dokončete kontrolu, vyřešte konflikt při stahování nebo po odstranění příčiny zopakujte neúspěšné zpracování cíle. Nenulové návratové kódy ponechte viditelné; || true příčinu skrývá.
Odstraňte krok nebo jeho spouštěč, aby se nespouštěla nová sestavení. Při rušení sestavení samostatně zkontrolujte všechny překlady, které už byly odeslány ke zpracování. Při vyřazení tohoto postupu odstraňte tajný údaj LINGO_API_KEY a agentovi odeberte právo zápisu.