--- title: Internacionalización (i18n) order: 8 icon: phosphor-duotone:translate tags: [guías, i18n] --- # Internacionalización (i18n) Traduce tus documentos a otros idiomas, cada uno con su propio prefijo de URL, su propio ``, y un selector de idioma automático - sin plugin, sin paso de construcción separado. ## Añadir un idioma El contenido traducido vive en `docs/i18n//`, reflejando tu árbol `docs/` regular página por página: ``` docs/ ├── index.md ├── guides/ │ └── setup.md └── i18n/ ├── es/ │ ├── index.md │ └── guides/ │ └── setup.md └── ar/ └── index.md ``` `` se convierte tanto en el nombre de la carpeta como en el prefijo de URL generado (`docs/i18n/es/guides/setup.md` → `/es/guides/setup/`), así que mantenlo corto - tanto un código de idioma simple (`es`, `fr`) como un par idioma-región (`pt-BR`, `zh-Hans`) funcionan, solo letras/dígitos/guiones. Tu árbol `docs/` regular es siempre el **idioma predeterminado**, construido sin prefijo en la raíz del sitio exactamente como lo es hoy - añadir `docs/i18n/` no cambia nada al respecto. Dale a cada idioma una etiqueta de visualización (y, para un idioma de derecha a izquierda, su propia dirección) en `bxsites.json`: ```json title="bxsites.json" linenums="1" { "i18n": { "defaultLocale": { "code": "en", "label": "English" }, "locales": [ { "code": "es", "label": "Español" }, { "code": "ar", "label": "العربية", "dir": "rtl" }, { "code": "pt-BR", "label": "Português (Brasil)", "flag": "🇧🇷" } ] } } ``` `defaultLocale` solo hace falta configurarlo si tu idioma predeterminado no es el inglés; `locales` es la lista de todo lo demás. Cada carpeta `docs/i18n//` se construye automáticamente en cuanto existe - `locales` simplemente proporciona su etiqueta de visualización y dirección de texto. Una carpeta sin una entrada coincidente en `locales` igualmente se construye (usando su código simple como su propia etiqueta), así que esto son metadatos, no lo que activa o desactiva la función. `flag` es opcional - el propio selector ya elige un emoji de bandera razonable para unos ~40 códigos de idioma comunes por sí solo (comprobando primero un código de región como `pt-BR`, y recurriendo después al idioma base `pt`). Establece `flag` tú mismo solo para anular esa suposición, o para un código que la búsqueda incorporada no reconoce (en ese caso recurre a un 🌐 simple). ## Qué se construye Cada idioma es una construcción real, totalmente independiente - su propio `search-index.json`, sus propios `assets/`, todo lo que produce una construcción normal - escrito bajo `site//` (`site/es/`, `site/ar/`). No hay nada que activar por idioma: en cuanto existe `docs/i18n/es/`, `bxSites build` lo recoge por sí solo. ## Páginas sin traducir Un idioma no necesita tener todas las páginas traducidas para ser utilizable. Una página que falte en `docs/i18n/es/` igualmente se construye en su URL esperada - mostrando el propio contenido del idioma predeterminado, con un pequeño aviso en la parte superior de la página indicando que aún no se ha traducido. Nada devuelve un 404, nada se ve a medio construir mientras una traducción está en progreso. La navegación de cada idioma siempre tiene exactamente la misma forma que la del idioma predeterminado - las mismas páginas, el mismo orden, el mismo anidamiento (lo que sea que ya produzca la propia estructura de carpetas de `docs/`, o una [`nav`](../configuration.md#nav) explícita) - solo con el título/contenido de cada página sustituido por su propia traducción donde exista una. Esto es también lo que hace funcionar al selector de idioma: cambiar de idioma te lleva a la *misma página*, traducida o no, nunca a la página de inicio de ese idioma. ## El selector de idioma En cuanto existe más de un idioma, cada tema renderiza automáticamente un desplegable de idioma en la cabecera - nada que activar, igual que el [selector de versión](../configuration.md#versionado). Muestra la bandera del idioma actual como disparador; al abrirlo se lista cada idioma con su propia bandera y etiqueta, marcando el actual como activo. Elige un idioma que no estés construyendo actualmente y simplemente no se renderizará en absoluto. ## Docs versionados y traducidos Consulta [Versionado](versioning.md) para el propio `docs/versions//`. Las versiones y los idiomas se combinan un nivel: coloca una carpeta `docs/versions//i18n//` junto a las propias páginas de una versión, reflejando la propia estructura de esa versión exactamente de la misma forma que un `docs/i18n//` de nivel superior refleja el propio `docs/`: ```text title="docs/versions/2.0/ layout" docs/ versions/ 2.0/ index.md guides/ setup.md i18n/ es/ index.md # traducida guides/ setup.md # las páginas sin traducir igualmente recurren al idioma predeterminado, igual que en el i18n de nivel superior ``` Esto construye `site/versions/2.0/es/`. Las propias páginas del idioma predeterminado de una versión (`site/versions/2.0/`) también obtienen un selector de idioma, listando solo los idiomas para los que *esa misma versión* tiene traducciones - una versión sin su propia subcarpeta `i18n/` se renderiza exactamente igual que antes de que existiera esto, sin selector mostrado. Cambiar de versión siempre vuelve al propio idioma predeterminado de esa versión (nunca asume que la versión de destino tiene la misma traducción); cambiar de idioma siempre se mantiene en la versión actual. ## Qué queda fuera de alcance (por ahora) - **La interfaz del tema permanece en inglés.** "Edit this page," "Last updated," el marcador de posición de búsqueda, y cadenas de interfaz similares todavía no se traducen por idioma - solo se traduce el contenido de tu propia página. La experiencia de lectura real de un idioma está completamente traducida; el mobiliario circundante del tema no lo está. - **El espejado de diseño RTL es básico, no pixel-perfecto.** `dir="rtl"` se establece correctamente, y la barra lateral/cabecera se reflejan de verdad, pero algunos detalles decorativos (el lado de la barra de acento de una admonición, por ejemplo) todavía no se voltean. - **Sin traducción automatizada.** Cada archivo de `docs/i18n//` se redacta a mano, igual que cualquier otra página de markdown - no hay ningún paso de traducción automática. ## Iconos personalizados e inclusiones Una referencia de icono `custom:` y un `::: include` se resuelven ambos contra los propios `docs/assets/`/contenido reutilizable de tu proyecto, independientemente de qué idioma se esté construyendo - son recursos compartidos, no algo que un traductor necesite duplicar por idioma. ## SEO Las páginas de cada idioma se incluyen en `sitemap.xml` y `llms.txt` junto a las del propio idioma predeterminado, de la misma forma que lo hacen las páginas [versionadas](../configuration.md#versionado).