Skip to main content

​
Developer reference localization (SDK & CLI)

Fixes the bug where switching language on an SDK or CLI page dropped the reader into the Documentation tab. Mintlify’s language switcher maps the current URL to the same slug under the target locale’s prefix; if no page exists there it falls back to the locale’s default tab. SDK/CLI previously existed only in English (href stubs + redirects), so every switch fell back to Documentation.

​
Policy: reference content is NOT translated

Every SDK/CLI reference page is English content at a unique per-locale path (es/developers/references/...). We deliberately do not translate this content:
  • The language switcher resolves because a real page exists at every locale path — the reader stays in the Developers tab.
  • Mintlify’s built-in UI chrome auto-localizes per locale on its own — search, “Copy page”, “Ask Assistant”, “Was this page helpful?”, prev/next, tab labels. That is platform UI keyed off the page’s locale; it needs nothing from us and is the localized experience the reader actually notices.
  • No translation runs, so there is no drift and no per-release translation cost.
Unique per-locale paths (never a shared English path) are what keep llms-full.txt clean: Mintlify emits only the default language into llms and never sees a URL twice. Sharing one English path across locales is what caused the earlier 8× duplication. scripts/reference-i18n.json records this per section as mode: "english-copy". The translate mode is still supported by the tooling if you ever want Mintlify to translate a section (see “Flipping to translated” below) — but nothing uses it today.

​
Keeping the English mirror fresh

Because the locale pages are English copies, they must be re-mirrored whenever the English source changes (otherwise a locale shows stale English):
Recommended: run sync-reference-i18n.mjs in CI (e.g. alongside the existing generate-llms-txt workflow) so edits to English SDK/CLI pages propagate to every locale automatically — then there is zero recurring manual work.

​
REQUIRED one-time dashboard step

In Mintlify dashboard → Settings → Translations, exclude the SDK and CLI reference trees from auto-translation, or Mintlify will translate these English-copy pages and start a drift treadmill. The globs to exclude:
Do not exclude monitoring-api or audit-logs-api — those keep real translated Get Started pages. This step is one-time: the globs already cover any future generated pages and any future locale. The switcher works with or without it; the exclusion only prevents translation churn.

​
Flipping a section to fully translated later

  1. Set its mode to translate in reference-i18n.json.
  2. Remove its path from the dashboard translation-exclusion globs above.
  3. For sdk/docs only, stop the SDK pipeline from overwriting it.
sync-reference-i18n.mjs then only seeds missing locale files and never clobbers a translation. No path or navigation change is needed — the structure is already correct.

​
Known limitation (by design)

SDK/CLI navigation group labels (e.g. “Get Started”, “Commands”, “Client”) are English in every locale. Top-level tab labels (“Desarrolladores”, etc.) and all built-in chrome are localized; only these sub-group labels are not. They are cheaply localizable via a one-time docs.json edit (same approach as PR #1400) with no drift, if you ever want them translated.