feat(i18n): add Stellar quickstart EN/ES + language switcher

docs.json

@@ -112,6 +112,8 @@
           {
             "group": "Guides",
             "pages": [
+              "guides/stellar-quickstart",
+              "guides/stellar-quickstart.es",
               "guides/stealth-payments",
               "guides/single-chain-agent",
               "guides/multichain-agent",
@@ -127,14 +129,10 @@
             "pages": [
               "guides/stellar-mainnet-deployment",
               "guides/stellar-payment-links",
-            "guides/stellar-payment-links",
               "guides/stellar-multisig-withdrawal",
               "guides/stellar-offline-signing",
               "guides/stellar-tx-simulation",
               "guides/stellar-explorer-recipes",
-              "guides/stellar-payment-links",
-              "guides/privacy-best-practices",
-              "guides/spectre-stellar-cookbook",
               "guides/stellar-federation",
               "guides/stellar-custom-assets",
               "guides/wraith-names-stellar"

docs/i18n.md

@@ -0,0 +1,271 @@
+# Internacionalización (i18n) — Guía para colaboradores
+# Internationalization (i18n) — Contributor Guide
+
+> **Language note:** This document is bilingual. The Spanish section mirrors the English one because it is itself a contributor-facing guide — translators need to read it.
+
+---
+
+## English
+
+### Background
+
+Mintlify does not have native multi-locale support. This repository implements a lightweight convention instead: translated pages live alongside their English source using a locale suffix in the filename, and each page carries a `<Card>` switcher at the top pointing at the other locale.
+
+The first translated page is `guides/stellar-quickstart.es.mdx`. It establishes the pattern for all future translations.
+
+### File naming convention
+
+| English source | Translated file |
+|---|---|
+| `guides/stellar-quickstart.mdx` | `guides/stellar-quickstart.es.mdx` |
+| `guides/some-guide.mdx` | `guides/some-guide.fr.mdx` |
+| `guides/some-guide.mdx` | `guides/some-guide.pt.mdx` |
+
+Rules:
+- Use the two-letter ISO 639-1 language code as the suffix before `.mdx`.
+- Keep the file in the **same directory** as the English source — no `locales/` subdirectory.
+- Never rename or move the English source when adding a translation.
+
+### Language switcher
+
+Every translated page must have a `<Card>` switcher as the **first element after the frontmatter**, pointing back to the English page. The English page must have a corresponding card pointing to each available translation.
+
+**English page** (`guides/my-guide.mdx`):
+```mdx
+---
+title: "My Guide"
+description: "..."
+---
+
+<Card title="🇪🇸 Leer en español" href="/guides/my-guide.es" icon="globe" />
+
+---
+(rest of page)
+```
+
+**Translated page** (`guides/my-guide.es.mdx`):
+```mdx
+---
+title: "Mi guía"
+description: "..."
+---
+
+<Card title="🇺🇸 Read in English" href="/guides/my-guide" icon="globe" />
+
+---
+(rest of page)
+```
+
+If a page has multiple translations, use a `<CardGroup>` instead of a single `<Card>`:
+
+```mdx
+<CardGroup cols={3}>
+  <Card title="🇺🇸 English" href="/guides/my-guide" icon="globe" />
+  <Card title="🇪🇸 Español" href="/guides/my-guide.es" icon="globe" />
+  <Card title="🇵🇹 Português" href="/guides/my-guide.pt" icon="globe" />
+</CardGroup>
+```
+
+### docs.json navigation
+
+Add both the English and translated pages to `docs.json` in the same navigation group, with the translated page immediately following its English source:
+
+```json
+{
+  "group": "Guides",
+  "pages": [
+    "guides/stellar-quickstart",
+    "guides/stellar-quickstart.es",
+    "guides/stealth-payments"
+  ]
+}
+```
+
+The Mintlify sidebar will display the `title` field from each page's frontmatter, so the ES page will show "Guía de inicio rápido — Stellar" automatically.
+
+### Translation workflow
+
+1. **Pick a page.** Start with high-traffic pages. Check site analytics or Discord for pages Spanish-speaking contributors ask about most.
+
+2. **Create the translated file.** Copy the English source:
+   ```bash
+   cp guides/my-guide.mdx guides/my-guide.es.mdx
+   ```
+
+3. **Translate the frontmatter.** Translate `title` and `description`. Keep `keywords` in English — they are used for search indexing and should match what users type in English even when reading in Spanish.
+
+4. **Translate the prose.** Translate all headings, paragraph text, callout text (`<Warning>`, `<Info>`), table headers and cells, and card titles in `<CardGroup>`.
+
+5. **Do not translate:**
+   - Code blocks (TypeScript, bash, JSON) — keep these identical to the English source
+   - `href` and `url` values inside `<Card>` components (other than the language switcher itself)
+   - Internal link targets (`/guides/stellar-fees` stays `/guides/stellar-fees` — the link points to the English page unless a translated version also exists)
+   - API field names and error message strings that appear inside prose
+
+6. **Add the language switcher.** Add the `<Card>` to the translated page pointing back to the English page. Add the reverse `<Card>` to the English source pointing to the new translation.
+
+7. **Update docs.json.** Add the translated page path immediately after the English entry in `navigation`.
+
+8. **Run the snippet checker** to confirm all code fences still parse cleanly:
+   ```bash
+   npm run check:snippets
+   ```
+
+9. **Open a pull request.** Tag at least one native speaker of the target language as a reviewer. The PR will not be merged without a native-speaker sign-off.
+
+### Reviewer checklist (native speaker sign-off)
+
+Before approving a translated PR, verify:
+
+- [ ] The translation reads naturally — not machine-translated or overly literal
+- [ ] Technical terms are consistent with how the Stellar/Soroban ecosystem uses them in Spanish (e.g., "comisión" not "tarifa" for fees, "contrato inteligente" not "contrato listo")
+- [ ] No prose was accidentally left in English (other than the intentional exceptions listed above)
+- [ ] Code comments in code blocks are acceptable left in English (they are low-priority; translate if you have the time)
+- [ ] The language switcher card appears at the top and links correctly
+- [ ] The page renders correctly in the Mintlify preview
+
+### Keeping translations up to date
+
+When the English source changes:
+
+1. Check the git diff to identify what prose changed.
+2. Apply equivalent changes to all translated files.
+3. If the change is non-trivial, re-request a native-speaker review.
+4. If a translation is significantly out of date (more than one major section behind), add an `<Info>` callout at the top of the translated page noting the discrepancy:
+
+```mdx
+<Info>
+  Esta página puede estar desactualizada. La versión en inglés fue actualizada recientemente.
+  [Ver la versión en inglés](/guides/my-guide) para el contenido más reciente.
+</Info>
+```
+
+Remove the callout once the translation is caught up.
+
+### Adding a new locale
+
+To add a locale not yet present in the project (e.g., Portuguese):
+
+1. Follow the file naming convention above (`.pt.mdx` suffix).
+2. Add the locale flag emoji and label to the language switcher `<CardGroup>` on the English page.
+3. Update this document's locale table (see "Supported locales" below).
+4. Find at least one native-speaker reviewer before the PR is merged.
+
+### Supported locales
+
+| Code | Language | Status | Pages translated |
+|---|---|---|---|
+| `es` | Spanish (Español) | Active | `guides/stellar-quickstart` |
+
+Add a row to this table when you start a new locale.
+
+---
+
+## Español
+
+### Contexto
+
+Mintlify no tiene soporte nativo para múltiples idiomas. Este repositorio implementa una convención ligera: las páginas traducidas coexisten con su fuente en inglés usando un sufijo de locale en el nombre del archivo, y cada página incluye un componente `<Card>` en la parte superior que apunta al otro idioma.
+
+La primera página traducida es `guides/stellar-quickstart.es.mdx`. Establece el patrón para todas las traducciones futuras.
+
+### Convención de nombres de archivo
+
+| Fuente en inglés | Archivo traducido |
+|---|---|
+| `guides/stellar-quickstart.mdx` | `guides/stellar-quickstart.es.mdx` |
+| `guides/some-guide.mdx` | `guides/some-guide.fr.mdx` |
+| `guides/some-guide.mdx` | `guides/some-guide.pt.mdx` |
+
+Reglas:
+- Usa el código ISO 639-1 de dos letras como sufijo antes de `.mdx`.
+- Mantén el archivo en el **mismo directorio** que la fuente en inglés — sin subdirectorio `locales/`.
+- Nunca cambies el nombre ni la ubicación de la fuente en inglés al añadir una traducción.
+
+### Selector de idioma
+
+Toda página traducida debe tener un componente `<Card>` como **primer elemento después del frontmatter**, apuntando de vuelta a la página en inglés. La página en inglés debe tener una tarjeta correspondiente que apunte a cada traducción disponible.
+
+**Página en inglés** (`guides/my-guide.mdx`):
+```mdx
+---
+title: "My Guide"
+description: "..."
+---
+
+<Card title="🇪🇸 Leer en español" href="/guides/my-guide.es" icon="globe" />
+
+---
+(resto de la página)
+```
+
+**Página traducida** (`guides/my-guide.es.mdx`):
+```mdx
+---
+title: "Mi guía"
+description: "..."
+---
+
+<Card title="🇺🇸 Read in English" href="/guides/my-guide" icon="globe" />
+
+---
+(resto de la página)
+```
+
+Si una página tiene múltiples traducciones, usa `<CardGroup>` en lugar de un solo `<Card>`.
+
+### Flujo de trabajo de traducción
+
+1. **Elige una página.** Empieza por las páginas con más tráfico o las que los colaboradores hispanohablantes piden con más frecuencia en Discord.
+
+2. **Crea el archivo traducido.** Copia la fuente en inglés:
+   ```bash
+   cp guides/my-guide.mdx guides/my-guide.es.mdx
+   ```
+
+3. **Traduce el frontmatter.** Traduce `title` y `description`. Deja `keywords` en inglés — se usan para indexación de búsqueda.
+
+4. **Traduce el texto.** Traduce todos los encabezados, párrafos, callouts (`<Warning>`, `<Info>`), encabezados y celdas de tablas, y títulos de tarjetas en `<CardGroup>`.
+
+5. **No traduzcas:**
+   - Los bloques de código (TypeScript, bash, JSON)
+   - Los valores de `href` y `url` dentro de los componentes `<Card>` (excepto el propio selector de idioma)
+   - Los destinos de enlaces internos
+   - Los nombres de campos de la API y los mensajes de error dentro del texto
+
+6. **Agrega el selector de idioma** en la página traducida apuntando de vuelta a la versión en inglés, y el correspondiente en la fuente en inglés.
+
+7. **Actualiza docs.json.** Agrega la ruta de la página traducida inmediatamente después de la entrada en inglés en `navigation`.
+
+8. **Ejecuta el verificador de fragmentos de código:**
+   ```bash
+   npm run check:snippets
+   ```
+
+9. **Abre un pull request.** Etiqueta al menos a un hablante nativo del idioma de destino como revisor. El PR no se fusionará sin la aprobación de un hablante nativo.
+
+### Lista de verificación para revisores (aprobación de hablante nativo)
+
+Antes de aprobar un PR traducido, verifica:
+
+- [ ] La traducción se lee de forma natural — sin calcos literales ni estilo de traducción automática
+- [ ] Los términos técnicos son consistentes con el uso del ecosistema Stellar/Soroban en español
+- [ ] Ningún texto quedó en inglés accidentalmente (excepto las excepciones intencionales listadas arriba)
+- [ ] El selector de idioma aparece en la parte superior y enlaza correctamente
+- [ ] La página se renderiza correctamente en la vista previa de Mintlify
+
+### Mantener las traducciones actualizadas
+
+Cuando la fuente en inglés cambie:
+
+1. Revisa el diff de git para identificar qué texto cambió.
+2. Aplica los cambios equivalentes en todos los archivos traducidos.
+3. Si la página traducida está significativamente desactualizada, agrega un callout `<Info>` al inicio indicando la discrepancia.
+
+---
+
+## Locales soportados
+
+| Código | Idioma | Estado | Páginas traducidas |
+|---|---|---|---|
+| `es` | Español | Activo | `guides/stellar-quickstart` |