Pipeline de traduction i18n à grande échelle

What's in this pack

This is the stack for the app team shipping in 10+ languages without a dedicated localization vendor — a backend engineer, a frontend engineer, and a part-time PM who all share the on-call rotation and cannot afford a per-string SaaS bill that scales linearly with the product. The job stops being "translate strings" and starts being "keep translations in sync with main on every PR without a human in the loop for the bulk path".

It is not the same job as the one in the translator's multi-lingual stack. That pack is for the human translator and localization engineer running a real pipeline with translators in the loop. This pack is for the dev team that wants to automate that pipeline end-to-end in CI and only escalate to a human reviewer when a gate fails. Same five stages — extract, translate, QA, validate, reinject — but the picks change because the operator changes.

The difference shows up in the tool choices. We keep Weblate and Tolgee because every pipeline still needs a TMS, but we add pre-commit (the CI gate orchestrator), typos (CI-friendly spell-checker), markdownlint (so the translated .md files don't break the docs build), the openai-python SDK (the LLM caller in your translation script), and transformers (so you can fine-tune or host an NMT model on your own GPU without an API bill). The bulk-translate path becomes code, not clicks.

Install in this order (extract → AI translate → QA gate → reinject)

1. Weblate — the TMS that holds the source of truth. Start here because every other tool either feeds it or reads from it. Weblate watches your git repo, extracts strings from gettext/xliff/json/Android XML/properties, and pushes completed translations back as commits. Self-hosted on Docker, configured against your existing GitHub or GitLab repo, this is the foundation.
2. Tolgee — the developer-friendly alternative. Pick Tolgee instead of Weblate if your reviewers are PMs and designers who need to see strings in-context on the running app (alt-click). Pick Weblate if your reviewers live in PRs. Most teams pick one and stick with it for years; both are listed because the right answer depends on who reviews translations.
3. LibreTranslate — the self-hosted NMT engine for the bulk path. Wire this into Weblate's automatic-suggestion backend so every new string gets a machine translation before a human ever sees it. No per-token cost, no rate limit, no compliance review for sending pre-launch strings to a third-party SaaS. The first 80% of UI strings ship through LibreTranslate without further escalation.
4. Hugging Face Transformers — when LibreTranslate's Argos model isn't fluent enough for your target languages and you need to fine-tune. Load NLLB-200 or M2M-100, fine-tune on your existing translation memory (export it as a TMX file from Weblate), and serve from your own GPU. This is the escape hatch for low-resource languages and post-edit-heavy locales where the off-the-shelf NMT loses fluency.
5. openai-python (or any LLM SDK) — the context-aware translator for strings that have to read like a human wrote them. Marketing copy, error messages users see in their language, onboarding screens. Your translation script reads the source string + screenshot URL + glossary + the last 3 translations of similar strings, builds a prompt, calls the LLM, and writes the result back to Weblate. Always pass the glossary in the prompt. Always.
6. Vale — the terminology gate. Configure a rule pack with your forbidden terms (login → sign in), brand terms that must never be translated (Pull Request, Slack), and tone constraints per locale (formal Sie in German, informal tu in French marketing). Vale runs on every PR via pre-commit. A glossary violation fails the build. No exceptions, no soft warnings.
7. LanguageTool — the grammar and style gate. Run it on the translated output, not the source. Catches the silent class of bugs where the translation is grammatically wrong in ways a non-speaker reviewer would never notice — German case, French agreement, Spanish ser/estar, Russian plural forms. Self-hosted as an HTTP API in your CI cluster.
8. typos — the spell-check gate. Rust-fast, ships as a single binary, runs in pre-commit. Catches the recieve / recieved / seperator class of bugs that survive LLM translation because the LLM was trained on the internet, which contains those typos at scale. Configure a per-locale dictionary for product names and you're done.
9. markdownlint — the structure gate for translated docs. When your README.md ships in 10 locales, you cannot have one locale's translation silently break the heading hierarchy, mismatch a list indent, or close a code fence in the wrong place. markdownlint catches all three. Run it on every translated .md in CI.
10. pre-commit — the orchestrator that wires the four gates together. One .pre-commit-config.yaml runs typos + Vale + LanguageTool + markdownlint on every staged file before commit and again in CI. If any gate fails, the commit fails, the PR fails, nothing reinjects. This is the file that turns the stack from "a pile of tools we ran once" into "a pipeline that holds the line on every PR".

How they fit together (CI-driven pipeline)

  source content (po / xliff / json / Android XML / md)
        │
        ▼
  ┌──── Weblate (or Tolgee) ─────┐
  │   extract on git push        │
  │   ─────────────────────────  │
  │   present strings via REST   │
  └──────────────┬───────────────┘
                 ▼
     ┌──── translation script ────┐
     │  for each string:          │
     │   • lookup translation memory │
     │   • build prompt (glossary + screenshot) │
     │   • route by string type:  │
     │      marketing → OpenAI SDK│
     │      UI bulk   → LibreTranslate │
     │      hard lang → Transformers (fine-tuned) │
     │   • write back to Weblate  │
     └──────────────┬─────────────┘
                    ▼
        ┌──── pre-commit gates ────┐
        │  Vale       (glossary)   │
        │  LanguageTool (grammar)  │
        │  typos      (spelling)   │
        │  markdownlint (.md shape)│
        │   ANY fail = PR fails    │
        └──────────────┬───────────┘
                       ▼
           reinject via Weblate commit → git → build

The gate row is the load-bearing piece. Without pre-commit orchestrating the four checkers, glossary drift, grammar bugs, spelling typos, and broken markdown all leak into production on different days through different paths. With it, every PR either passes all four or doesn't merge.

Tradeoffs you'll hit

• OpenAI SDK vs self-hosted Transformers vs LibreTranslate — these three are different cost/quality/privacy points. LLM via OpenAI SDK is highest quality for context-sensitive strings (marketing, errors) and costs cents per thousand strings; LibreTranslate is free and runs in your VPC but loses fluency on low-resource languages; Transformers fine-tuned on your own TM is the escape hatch when neither works. The production pattern: route by string type, not by tool. Marketing copy → LLM. Bulk UI → LibreTranslate. Locales where LibreTranslate is bad → fine-tuned NMT via Transformers.
• Weblate vs Tolgee vs SaaS (Lokalise/Crowdin/Phrase) — SaaS ships faster but locks you in and prices per string. With a 50,000-string app in 12 locales, the math gets unfriendly fast. Weblate is the right default for teams whose reviewers live in PRs; Tolgee is the right default for teams whose reviewers need in-context editing. Stick with SaaS only when integrations you genuinely use justify the bill.
• CI gates as soft warnings vs hard failures — soft warnings get ignored. Hard failures cause occasional drama when a translation is genuinely fine and the gate is wrong. The right answer is hard failures with a documented override path: an engineer adds a # vale-ignore: TermsCheck comment with a code review justification, the PR proceeds, the override gets audited weekly. Never run the gates as advisory.
• Translation memory ownership — your TM is more sensitive than your code. It contains every release note before launch, every customer support reply, every legal disclaimer. Self-host the TMS (Weblate or Tolgee) and only send strings to a third-party LLM after PII and embargoed-content redaction. The LibreTranslate + self-hosted Transformers path exists for exactly this reason.

Common pitfalls

• Placeholder breakage — the LLM helpfully translates {username} to {nombreusuario} and the app crashes on next render. Turn on Weblate's placeholder check; configure your translation script to lock placeholders before the LLM call and substitute them back after.
• Forgetting to pass the glossary in the LLM prompt — the single most common bug in homegrown translation scripts. Without the glossary, the LLM picks a new word for "workspace" every call. The fix is one line in the prompt template; do not skip it.
• Routing by language instead of by string type — "all French goes through LLM" sounds cheap until your French marketing copy reads like a robot. Route by string type: marketing → LLM, UI bulk → NMT, regardless of language.
• Treating CI gates as advisory — the moment one engineer overrides a Vale failure without code review, the gate is dead. Either it's a hard fail or it's nothing.
• Skipping markdownlint on translated docs — translated README.md files break the docs build at 2am because a Spanish translator put a * where a - was. markdownlint is the cheapest insurance in this pack; turn it on first.
• No human-in-the-loop sampler — a fully-automated pipeline drifts. Sample 1% of merged translations into a manual review queue weekly. The metrics from that sample tell you which gates need tuning and which locales need a Transformers fine-tune.