Internacionalización (i18n)
On this page
Internacionalización (i18n)
Traduce tus documentos a otros idiomas, cada uno con su propio prefijo de
URL, su propio <html lang dir>, 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/<code>/, 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
<code> 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:
{
"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/<code>/ 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/<code>/ (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 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. 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 para el propio docs/versions/<name>/.
Las versiones y los idiomas se combinan un nivel: coloca una carpeta
docs/versions/<name>/i18n/<code>/ 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/<code>/ de nivel superior refleja el
propio docs/:
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/<code>/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.