Internacionalización (i18n)
En esta página
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.yaml:
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: 🇧🇷 }
{
"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.
Interfaz del tema (cadenas de UI)
Todo el texto de interfaz que rodea cada tema integrado - el marcador de posición de búsqueda, "En esta página," "Editar esta página," "Última actualización," la página 404, el título de la página de etiquetas, y el propio aviso de "aún no traducida" - también se traduce por idioma, no solo el contenido de tu propia página.
Cuatro idiomas incluyen una traducción integrada de fábrica: de, es,
it y ja. Construir cualquiera de esos códigos de idioma obtiene
automáticamente una interfaz completamente traducida, nada que
configurar. Cualquier otro código de idioma (o una página que prefieras
redactar de otra forma) recurre al inglés - sobrescribe solo las claves
que te importen con tus propios strings en la entrada de ese idioma en
bxsites.yaml:
i18n:
defaultLocale: { code: en, label: English }
locales:
- code: fr
label: Français
strings:
searchPlaceholder: Rechercher dans la documentation...
onThisPage: Sur cette page
- code: es
label: Español
strings: { toggleDarkMode: Cambiar a modo nocturno }
{
"i18n": {
"defaultLocale": { "code": "en", "label": "English" },
"locales": [
{
"code": "fr",
"label": "Français",
"strings": {
"searchPlaceholder": "Rechercher dans la documentation...",
"onThisPage": "Sur cette page"
}
},
{
"code": "es",
"label": "Español",
"strings": { "toggleDarkMode": "Cambiar a modo nocturno" }
}
]
}
}
Un idioma con traducción integrada (como es arriba) puede seguir
sobrescribiendo claves individuales de la misma forma - tus propios
strings siempre ganan tanto a la traducción integrada como al valor
predeterminado en inglés. El propio defaultLocale también puede llevar
sus propios strings, para un proyecto cuyo idioma predeterminado no sea
el inglés y que quiera su propia redacción de interfaz en lugar de
recurrir al valor predeterminado en inglés.
El conjunto completo de claves sobrescribibles: searchPlaceholder,
searchAriaLabel, searchNoResults, toggleDarkMode,
toggleNavigation, toggleSection (marcador {title}), repository,
version, language (marcador {label}), onThisPage, editThisPage,
downloadMarkdown, lastUpdated, notTranslatedNotice (marcador
{locale}), notFoundTitle, notFoundBody, tagsTitle y
pageNavigation.
Qué queda fuera de alcance (por ahora)
- La interfaz del blog permanece en inglés. Las propias cadenas de UI
del subsistema de blog ("Categories," "Archive," "Read more," "N min
read," ...) todavía no están cubiertas por el override de
stringsde arriba - solo lo está el resto de la interfaz del tema. - El valor de fecha de
lastUpdatedno depende del idioma. Su etiqueta se traduce; el propio valor de fecha/hora se sigue formateando igual sin importar el idioma. - 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.