docs(i18n): demonstrate translator with pt-BR backfill of CLAUDE.md + architecture/ARCHITECTURE.md

Updates docs/guides/I18N.md with a 'Translation pipeline (recommended)' section documenting the npm run i18n:run / :check / :run:dry flow, required env vars, state file semantics, and the legacy-script deprecation notice. The legacy Quick-Reference row for the Python translator is replaced with the new npm script entry. Re-translates two sources end-to-end through the new pipeline: - CLAUDE.md (1 chunk, 23k chars) - docs/architecture/ARCHITECTURE.md (14 chunks, 74k chars, one timeout retry) Both translations now have a fresh language bar regenerated from config/i18n.json (41 locales), an H1 heading with the native language tag, and prose translated into Brazilian Portuguese while preserving markdown syntax, code blocks, command names, env var identifiers, and version numbers verbatim. .i18n-state.json records the SHA-256 hash for each source and target. A second invocation with no source changes correctly reports 'work units: 0 (skipped up-to-date: 2 of 2)' and `npm run i18n:check` exits 0 — confirming the hash-based incremental + drift detection paths both work as designed. - Elapsed: ~10 min total at concurrency=4 - Cost: ~75k chars output through the configured backend Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-07-26 09:52:11 +03:00 · 2026-05-13 17:17:27 -03:00
parent dfe9a3e288
commit ae3d73a2e7
4 changed files with 1187 additions and 688 deletions
--- a/docs/guides/I18N.md
+++ b/docs/guides/I18N.md
@@ -4,16 +4,74 @@ OmniRoute supports **30 languages** with full dashboard UI translation, translat

 🌐 **Languages:** 🇺🇸 [English](./I18N.md) | 🇧🇷 [Português (Brasil)](./pt-BR/I18N.md) | 🇪🇸 [Español](./es/I18N.md) | 🇫🇷 [Français](./fr/I18N.md) | 🇩🇪 [Deutsch](./de/I18N.md) | 🇮🇹 [Italiano](./it/I18N.md) | 🇷🇺 [Русский](./ru/I18N.md) | 🇨🇳 [中文 (简体)](./zh-CN/I18N.md) | 🇯🇵 [日本語](./ja/I18N.md) | 🇰🇷 [한국어](./ko/I18N.md) | 🇸🇦 [العربية](./ar/I18N.md) | 🇮🇳 [हिन्दी](./hi/I18N.md) | 🇹🇭 [ไทย](./th/I18N.md) | 🇹🇷 [Türkçe](./tr/I18N.md) | 🇺🇦 [Українська](./uk-UA/I18N.md) | 🇻🇳 [Tiếng Việt](./vi/I18N.md) | 🇧🇬 [Български](./bg/I18N.md) | 🇩🇰 [Dansk](./da/I18N.md) | 🇫🇮 [Suomi](./fi/I18N.md) | 🇮🇱 [עברית](./he/I18N.md) | 🇭🇺 [Magyar](./hu/I18N.md) | 🇮🇩 [Bahasa Indonesia](./id/I18N.md) | 🇲🇾 [Bahasa Melayu](./ms/I18N.md) | 🇳🇱 [Nederlands](./nl/I18N.md) | 🇳🇴 [Norsk](./no/I18N.md) | 🇵🇹 [Português (Portugal)](./pt/I18N.md) | 🇷🇴 [Română](./ro/I18N.md) | 🇵🇱 [Polski](./pl/I18N.md) | 🇸🇰 [Slovenčina](./sk/I18N.md) | 🇸🇪 [Svenska](./sv/I18N.md) | 🇵🇭 [Filipino](./phi/I18N.md) | 🇨🇿 [Čeština](./cs/I18N.md)

+## Translation pipeline (recommended — v3.8.0)
+
+OmniRoute uses a hash-based incremental translator for docs, backed by an
+OpenAI-compatible LLM endpoint (typically `cx/gpt-5.4-mini` through OmniRoute
+Cloud):
+
+```bash
+# Run translations (incremental — only touches changed sources)
+npm run i18n:run
+
+# Limit to one locale
+npm run i18n:run -- --locale=pt-BR
+
+# Specific files (comma-separated, repo-relative paths)
+npm run i18n:run -- --files=CLAUDE.md,docs/architecture/ARCHITECTURE.md
+
+# Force retranslate everything (expensive)
+npm run i18n:run -- --force
+
+# Preview what would happen (no API calls, no writes)
+npm run i18n:run:dry
+
+# CI gate — exits non-zero if state is drifting
+npm run i18n:check
+```
+
+**Source of truth.** `config/i18n.json` lists every locale (UI + docs) plus
+the RTL set and the `docsExcluded` codes. The runtime config in
+`src/i18n/config.ts` is a thin adapter over that JSON.
+
+**Backend.** Configured via env (set in `.env`, never committed):
+
+| Variable                            | Purpose                                 |
+| ----------------------------------- | --------------------------------------- |
+| `OMNIROUTE_TRANSLATION_API_URL`     | OpenAI-compatible base URL, e.g. `…/v1` |
+| `OMNIROUTE_TRANSLATION_API_KEY`     | bearer token (kept out of logs)         |
+| `OMNIROUTE_TRANSLATION_MODEL`       | model id, e.g. `cx/gpt-5.4-mini`        |
+| `OMNIROUTE_TRANSLATION_TIMEOUT_MS`  | optional, default `60000`               |
+| `OMNIROUTE_TRANSLATION_CONCURRENCY` | optional, default `4`                   |
+
+**State tracking.** `.i18n-state.json` (committed) keeps SHA-256 hashes per
+source + per locale. Drift detection is automatic and deterministic — no API
+calls in `i18n:check`.
+
+**Output shape.** Each translated file gets a top-level `# <heading>
+(<native>)` line, a `🌐 Languages: …` bar, an `---` separator, and the
+translated body. That layout matches what `scripts/check/check-docs-sync.mjs`
+already enforces for `llm.txt` and `CHANGELOG.md` mirrors.
+
+### Legacy scripts (deprecated)
+
+The older Python script (`scripts/i18n/i18n_autotranslate.py`) and the
+Google-Translate-backed generator (`scripts/i18n/generate-multilang.mjs`)
+still exist with a deprecation banner. They will be removed in v3.10. The
+`messages` and `readme` modes of `generate-multilang.mjs` (UI strings + root
+README variants) are not yet handled by the new pipeline and are still used.
+
 ## Quick Reference

-| Task                   | Command                                                                                      |
-| ---------------------- | -------------------------------------------------------------------------------------------- |
-| Generate translations  | `node scripts/i18n/generate-multilang.mjs messages`                                          |
-| Translate docs (LLM)   | `python3 scripts/i18n/i18n_autotranslate.py --api-url <url> --api-key <key> --model <model>` |
-| Validate a locale      | `python3 scripts/i18n/validate_translation.py quick -l cs`                                   |
-| Check code keys        | `python3 scripts/i18n/check_translations.py`                                                 |
-| Generate QA report     | `node scripts/i18n/generate-qa-checklist.mjs`                                                |
-| Visual QA (Playwright) | `node scripts/i18n/run-visual-qa.mjs`                                                        |
+| Task                    | Command                                                    |
+| ----------------------- | ---------------------------------------------------------- |
+| Translate docs (LLM)    | `npm run i18n:run` (preferred — incremental, hash-based)   |
+| Translate UI strings    | `node scripts/i18n/generate-multilang.mjs messages`        |
+| Check translation drift | `npm run i18n:check`                                       |
+| Validate a locale       | `python3 scripts/i18n/validate_translation.py quick -l cs` |
+| Check code keys         | `python3 scripts/i18n/check_translations.py`               |
+| Generate QA report      | `node scripts/i18n/generate-qa-checklist.mjs`              |
+| Visual QA (Playwright)  | `node scripts/i18n/run-visual-qa.mjs`                      |

 ## Architecture