--- title: Soporte Multi-Idioma description: Agrega soporte multi-idioma de primera clase a tu sitio de documentación Thally con traducciones en tiempo de compilación y un selector de idioma. url: https://docs.thally.io/es/guides/multi-language --- # Soporte Multi-Idioma Agrega soporte multi-idioma de primera clase a tu sitio de documentación Thally con traducciones en tiempo de compilación y un selector de idioma. Thally soporta documentación multi-idioma en tiempo de compilación. Los archivos MDX traducidos se confirman en tu repositorio, lo que te brinda SSG completo, costo cero en tiempo de ejecución y URLs realmente indexables para cada locale. En Thally Cloud, selecciona los idiomas en **Configuración del sitio → Idiomas**. Las traducciones administradas usan los Créditos de IA compartidos del espacio de trabajo; no se configura ninguna clave de API para este flujo. Los comandos CLI y las opciones de clave de API que aparecen a continuación se ejecutan en tu propio entorno y no forman parte de la configuración de Thally Cloud. **Por qué traducciones en tiempo de compilación:** - Los archivos MDX traducidos están bajo control de versiones — revisables y editables como cualquier otro contenido - Cada traducción publicada obtiene una URL propia (p. ej. `/es/introduction`). Los fallbacks sin traducción no son indexables. - Funciona con cualquier hosting sin infraestructura edge - Sin almacén KV, sin llamadas API en tiempo de ejecución, sin costo por solicitud --- ## Estructura de URL - **Locale predeterminado** — `/introduction`, `/guides/getting-started` ← sin prefijo, totalmente compatible con versiones anteriores - **Locales secundarios** — `/es/introduction`, `/es/guides/getting-started` --- ## Paso 1 — Configurar i18n en docs.json Agrega un bloque `i18n` a tu `docs.json`: ```json { "i18n": { "defaultLocale": "en", "locales": [ { "code": "en", "label": "English" }, { "code": "es", "label": "Español" }, { "code": "fr", "label": "Français" } ] }, "tabs": [...] } ``` Una vez agregado esto, un **selector de idioma** (ícono de globo) aparecerá automáticamente en la barra superior. --- ## Paso 2 — Traducir páginas con la CLI Ejecuta el comando de traducción para generar archivos MDX traducidos para un locale: ```bash npx create-thally-docs translate --locale es ``` Esto traduce **todas las páginas** y las escribe en `src/content/es/`. ### Traducir páginas específicas ```bash npx create-thally-docs translate --locale es --pages introduction,guides/getting-started ``` ### Sobrescribir traducciones existentes ```bash npx create-thally-docs translate --locale es --force ``` ### Todas las opciones | Bandera | Descripción | |---------|-------------| | `--locale ` | Locale de destino — requerido (debe coincidir con un código en la configuración i18n de `docs.json`) | | `--pages ` | IDs de página separados por comas para traducir (omitir para todas las páginas) | | `--force` | Sobrescribir archivos de traducción existentes | | `--api-key ` | Clave API de Anthropic (usa `ANTHROPIC_API_KEY` como variable de entorno si no se especifica) | | `--model ` | Modelo Claude a usar (predeterminado: `claude-sonnet-4-6`) | | `--yes`, `-y` | Omitir la confirmación | --- ## Paso 3 — Estructura de archivos de contenido Después de ejecutar `translate`, tu directorio de contenido se verá así: ``` src/content/ ├── introduction.mdx ← principal (inglés, sin cambios) ├── guides/ │ └── getting-started.mdx ├── es/ ← traducciones al español │ ├── introduction.mdx │ └── guides/ │ └── getting-started.mdx └── fr/ └── introduction.mdx ``` Puedes editar los archivos traducidos igual que cualquier otro contenido MDX. --- ## Calidad de la traducción El comando de traducción usa Claude para traducir tu documentación con estas reglas estrictas: - Traduce todo el texto en prosa, encabezados y párrafos - Traduce `title`, `description` y `keywords` del frontmatter - Preserva todas las etiquetas de componentes MDX textualmente (``, ``, ``, etc.) - Preserva todos los bloques de código e código en línea tal como están - Preserva todas las URLs y rutas de archivos --- ## Comportamiento de reserva Cuando existe una página fuente pero falta su traducción, Thally muestra el contenido en el idioma fuente con un banner informativo. Una traducción huérfana cuya página fuente fue eliminada devuelve 404. > ⚠️ Esta página aún no ha sido traducida a **es**. Mostrando la versión original en **EN**. Si el hash de origen registrado en una traducción gestionada por IA difiere del contenido actual, Thally muestra un banner de antigüedad: > Esta traducción puede estar desactualizada. [Ver original →] Ambos banners solo aparecen en rutas de locales secundarios, la ruta principal nunca se ve afectada. Las traducciones humanas o sin marcador de origen no se consideran antiguas a partir de las fechas del despliegue; revisa su vigencia manualmente. ### Anclas de encabezado en páginas traducidas Los IDs de las anclas de encabezado conservan los caracteres no latinos. Un encabezado traducido como "Überblick" produce el ancla `#überblick`, y "日本語 API" se convierte en `#日本語-api`. Esto significa que los enlaces a secciones dentro de las páginas traducidas usan el texto traducido, no ASCII transliterado. --- ## Navegación específica por idioma Por defecto, todos los idiomas comparten la navegación del `tabs` raíz. Para proporcionar etiquetas traducidas o una estructura de páginas diferente, agrega un mapa `navigation` bajo `i18n`: ```json { "i18n": { "defaultLocale": "en", "locales": [ { "code": "en", "label": "English" }, { "code": "es", "label": "Español" } ], "navigation": { "es": [ { "tab": "Empezar", "groups": [ { "group": "Inicio", "pages": ["introduction", "quickstart"] } ] } ] } } } ``` Cada entrada usa la misma estructura de array `tabs` que la raíz. Usa IDs de páginas sin prefijo de idioma: Thally agrega el locale a las rutas. Cuando un idioma no tiene entrada en `navigation`, Thally recurre al `tabs` raíz. Esta navegación se refleja en la barra lateral, las migas de pan y los enlaces anterior/siguiente. --- ## Selector de idioma Una vez que tienes 2 o más locales configurados, aparece un **ícono de globo** en la barra superior. Al hacer clic, se abre un menú desplegable con todos los locales configurados. Seleccionar un locale navega a la misma página en ese locale. --- ## SEO Thally agrega etiquetas `hreflang` y `canonical` solo cuando la página tiene un archivo MDX traducido y ni la fuente ni la traducción están ocultas o marcadas como `noindex`: ```html ``` Las traducciones reales usan su propia URL de locale como canónica. Un fallback sin traducción se marca como `noindex` y se canonicaliza a la URL fuente, para que los rastreadores no indexen contenido en inglés como si fuera otro idioma. --- ## Usar la herramienta MCP Si usas el servidor MCP de Thally, puedes traducir documentación directamente desde tu asistente de IA: ```json { "name": "translate_docs", "arguments": { "projectDir": "/path/to/my-docs", "locale": "es", "apiKey": "sk-ant-..." } } ``` Consulta [Servidor MCP](/guides/mcp-server) para instrucciones de configuración. --- ## Inicializar con i18n Al inicializar un nuevo proyecto, puedes habilitar el soporte multi-idioma desde el principio: ```bash npx create-thally-docs my-docs ``` Cuando se te pregunte **"¿Habilitar soporte multi-idioma?"**, ingresa `y` y proporciona tus códigos de locale (p. ej. `es,fr,de`). El bloque `i18n` se escribirá en `docs.json` automáticamente.