> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference i18n.README

# 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):

```bash theme={null}
# SDK Get Started + CLI (hand-authored) — run after editing those English pages.
# OVERWRITES the english-copy locale files from English; idempotent.
node scripts/sync-reference-i18n.mjs          # --check for a dry run

# SDK API reference (machine-generated) — refreshed automatically every SDK
# release by javascript-sdk's pipeline:
npm run create-docs && npm run copy-docs-local -- --target /path/to/mintlify-docs
```

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:

```
**/developers/references/sdk/**
**/developers/references/cli/**
```

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.