GitLab CI/CD

Spusťte Lingo.dev v GitLab CI, aby se každý merge request, který přidá nebo změní zdrojové řetězce, vrátil s už doplněnými překlady. Pipeline běží lingo push, engine překládá jen nové nebo změněné klíče a výsledek commitne přímo do MR větve — překlady se objeví v diffu MR a projdou kontrolou ještě předtím, než je někdo sloučí. Na výchozí větev se tak nic nedostane bez kontroly.

Co budete potřebovat#

• Organizaci a engine v Lingo.dev a také service API key (Dashboard → API Keys → create, type service).

• Projekt nakonfigurovaný pro Lingo.dev. Jednou ho vygenerujte pomocí:

  bashCopy

  npx @lingo.dev/cli@latest init   # scaffolds .lingo/config.json
  npx @lingo.dev/cli@latest link   # connects the project to your org + engine

  .lingo/config.json určuje zdrojový a cílový jazyk a source globy:

  jsonCopy

  {
    "sourceLocale": "en",
    "targetLocales": ["es", "fr", "de", "zh"],
    "files": [{ "pattern": "locales/en.json" }],
    "orgId": "org_...",
    "engineId": "eng_..."
  }

• Commitnutý výchozí stav. Při úplně prvním spuštění přeložte vše a commitněte to, aby CI mělo lockfile, se kterým může porovnávat změny:

  bashCopy

  npx @lingo.dev/cli@latest push --backfill-missing --wait
  git add locales .lingo && git commit -m "chore(i18n): baseline translations"

Přístupové tokeny#

V Settings → CI/CD → Variables přidejte dvě maskované proměnné CI/CD:

• LINGO_API_KEY — váš service key pro Lingo.dev (lingo_sk_...). CLI ho automaticky načte pro ověření.
• GITLAB_PUSH_TOKEN — Project Access Token s rozsahem write_repository (role Developer). Díky němu může CI commitnout překlady zpět do MR větve.

Pipeline#

Commitněte tento .gitlab-ci.yml. Spouští se pro merge requesty mířící do výchozí větve a pushne překlady zpět do zdrojové větve MR:

stages:
  - localize

localize:
  stage: localize
  image: node:22-alpine
  rules:
    # Only on merge requests that target the default branch.
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH'
  before_script:
    - apk add --no-cache git
  script:
    # Pin the CLI version — never @latest; bump deliberately after testing.
    # --wait blocks until the engine finishes and writes files: since 1.6.0
    # `push` is async by default (it submits the run and exits), so CI must
    # wait to have something to commit.
    - npx -y @lingo.dev/cli@1.6.0 push --wait
    - |
      if [ -z "$(git status --porcelain)" ]; then
        echo "Translations already up to date — nothing to commit."
        exit 0
      fi
      git config user.name "lingo-bot"
      git config user.email "bot@lingo.dev"
      git add locales .lingo/lock.json
      # [skip ci] keeps the bot's own commit from re-triggering this pipeline.
      git commit -m "chore(i18n): sync translations [skip ci]"
      git push "https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" "HEAD:${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME}"

Vyzkoušejte si to#

git checkout -b feat/new-strings
# add or change a key in locales/en.json
git commit -am "feat: add strings" && git push -u origin feat/new-strings
# open an MR feat/new-strings -> main (UI, or: glab mr create --fill --target-branch main)

MR pipeline spustí lingo push --wait, commitne locales/{...}.json spolu s aktualizovaným .lingo/lock.json do MR větve a překlady se objeví v diffu. Kontrolující pak může upravit libovolnou hodnotu a následně MR sloučit.

Jak ruční úpravy zůstávají zachované#

lingo push zachovává ruční úpravy po jednotlivých klíčích:

• Upravíte cílový řetězec (jeho anglický zdroj zůstane beze změny) → tento řetězec se zachová; všechny ostatní klíče se dál překládají.
• Anglický zdroj za upraveným klíčem se změní → pro tento klíč se vygeneruje nový překlad (změnil se význam).
• Přidá se nový zdrojový klíč → přeloží se a přidá, i do souborů, které obsahují ruční úpravy.

Oprava od kontrolujícího v MR tak přežije každé další spuštění pipeline, zatímco nové a změněné klíče přibývají automaticky.

Režimy push#

• lingo push — přírůstkový; výchozí pro CI. Překládá jen nové nebo změněné klíče, vše ostatní zachovává. V CI přidejte --wait, aby se čekalo až do zapsání výstupů (od verze 1.6.0+ je výchozí chování asynchronní).
• lingo push --backfill-missing — první push / bootstrap nového jazyka; vyplní cílové soubory, které ještě neexistují. Není určený pro průběžné změny.
• lingo push --force --yes — znovu přeloží vše od nuly (přepíše ruční úpravy). Používá se jen výjimečně.

Přizpůsobení#

• Automatický commit do výchozí větve místo do MR: použijte spouštěč na $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH a push zpět do $CI_DEFAULT_BRANCH. Je to jednodušší, ale výstup AI se dostane do výchozí větve bez kontroly.
• Připněte konkrétní řetězce: použijte preservedKeys / lockedKeys v .lingo/config.json, aby vybrané klíče zůstaly pevně dané, i když se jejich zdroj změní.
• Self-hosted GitLab: funguje beze změny. Na gitlab.com musí nové účty před spuštěním CI jobů na sdílených runnerech projít ověřením identity.

Další kroky#