Internacionalización (i18n)
Starlight proporciona soporte incorporado para sitios multilingües, incluidas las rutas, el contenido de respaldo y el soporte completo de idiomas de derecha a izquierda (RTL).
Configura i18n
-
Indícale a Starlight los idiomas que admites pasando
locales
ydefaultLocale
a la integración de Starlight:Tu
defaultLocale
se utilizará para el contenido y las etiquetas de la UI de respaldo, por lo que elige el idioma en el que es más probable que comiences a escribir contenido o que ya tengas contenido. -
Crea un directorio para cada idioma en
src/content/docs/
. Por ejemplo, para la configuración mostrada anteriormente, crea las siguientes carpetas:Directorysrc/
Directorycontent/
Directorydocs/
Directoryar/
- …
Directoryen/
- …
Directoryzh-cn/
- …
-
Ahora puedes agregar archivos de contenido en los directorios de tu idioma. Utiliza el mismo nombre de archivo para asociar páginas entre idiomas y aprovechar todas las características de internacionalización (i18n) de Starlight, como contenido de respaldo, avisos de traducción y más.
Por ejemplo, crea
ar/index.md
yen/index.md
para representar la página de inicio en árabe e inglés, respectivamente.
Para escenarios de i18n más avanzados, Starlight también admite la configuración de internacionalizaciónutlizando la opción i18n
de Astro.
Usa una raíz de configuración regional
Puedes usar una raíz de configuración regional para servir un idioma sin ningún prefijo i18n en tu ruta. Por ejemplo, si el inglés es tu configuración regional, una ruta de página en inglés se vería como /about
en lugar de /en/about
.
Para establecer una configuración regional, usa la clave root
en tu configuración de locales
. Si la configuración regional raíz también es la configuración regional predeterminada para tu contenido, elimina defaultLocale
o configúralo en 'root'
.
Cuando uses una root
locale, mantén las páginas para ese idioma directamente en src/content/docs/
en lugar de en una carpeta de idioma dedicada. Por ejemplo, aquí están los archivos de la página de inicio para inglés y chino cuando se usa la configuración anterior:
Directorysrc/
Directorycontent/
Directorydocs/
- index.md
Directoryzh-cn/
- index.md
Sitios monolingües
De forma predeterminada, Starlight es un sitio monolingüe (en inglés). Para crear un sitio de un solo idioma en otro idioma, configúralo como el root
en tu configuración de locales
:
Esto te permite anular el idioma predeterminado de Starlight sin habilitar otras características de internacionalización para sitios multilingües, como el selector de idioma.
Contenido de respaldo
Starlight espera que crees páginas equivalentes en todos tus idiomas. Por ejemplo, si tienes un archivo en/about.md
, crea un archivo about.md
para cada otro idioma que admitas. Esto permite que Starlight proporcione automáticamente contenido de respaldo para las páginas que aún no se han traducido.
Si no hay una traducción disponible para un idioma, Starlight mostrará a los lectores el contenido de esa página en el idioma predeterminado (establecido mediante defaultLocale
). Por ejemplo, si aún no has creado una versión en francés de tu página Acerca de y tu idioma predeterminado es el inglés, los visitantes a /fr/about
verán el contenido en inglés de /en/about
con un aviso de que esta página aún no se ha traducido. Esto te ayuda a agregar contenido en tu idioma predeterminado y luego traducirlo progresivamente cuando tus traductores tengan tiempo.
Traduce el título del sitio
Por defecto, Starlight usará el mismo título del sitio para todos los idiomas.
Si necesitas personalizar el título para cada idioma, puedes pasar un objeto a title
en las opciones de Starlight:
Traduce la UI de Starlight
Además de alojar archivos de contenido traducidos, Starlight te permite traducir las etiquetas de UI predeterminadas (p. ej. el encabezado “En esta página” en la tabla de contenidos) para que tus lectores puedan experimentar tu sitio completamente en el idioma seleccionado.
Alemán, árabe, checo, chino, chino (Taiwán), coreano, danés, eslovaco, español, francés, gallego, hebreo, hindi, indonesio, inglés, italiano, japonés, neerlandés, noruego bokmal, persa, polaco, portugués, rumano, ruso, sueco, turco, ucraniano y vietnamita los strings de UI traducidos se proporcionan de forma predeterminada, y damos la bienvenida a contribuciones para agregar más idiomas predeterminados.
Puedes proprocionar traducciones para idiomas adicionales, o editar nuestras etiquetas predeterminadas, a través de la colección de datos i18n
.
-
Configura la colección de datos
i18n
ensrc/content/config.ts
si aún no está configurada: -
Crea un archivo JSON en
src/content/i18n/
para cada idioma adicional para el cual deseas proporcionar strings de traducción de la UI. Por ejemplo, esto agregaría archivos de traducción para árabe y chino simplificado:Directorysrc/
Directorycontent/
Directoryi18n/
- ar.json
- zh-CN.json
-
Agrega traducciones para las claves que deseas traducir en los archivos JSON. Traduce solo los valores, dejando las claves en inglés (p. ej.
"search.label": "Buscar"
).Estos son los valores predeterminados en inglés de las cadenas existentes que se incluyen en Starlight:
Los bloques de código de Starlight están impulsados por la biblioteca Expressive Code. Puedes establecer traducciones para las cadenas de UI en el mismo archivo JSON utilizando las llaves
expressiveCode
:El modal de búsqueda de Starlight está impulsado por la biblioteca Pagefind. Puedes establecer traducciones para la UI de Pagefind en el mismo archivo JSON utilizando claves
pagefind
:
Extiende el esquema de traducción
Agrega claves personalizadas a los diccionarios de traducción de tu sitio estableciendo extend
en las opciones de i18nSchema()
.
En el siguiente ejemplo, una clave nueva, opcional custom.label
se agrega a las claves predeterminadas:
Aprende más sobre los esquemas de colección de contenido en “Definir un esquema de colección” en la documentación de Astro.
Usar traducciones de UI
Puedes acceder a las strings de UI integradas de Starlight, así como a las cadenas de UI definidas por el usuario y proporcionadas por plugins a través de una API unificada impulsada por i18next. Esto incluye soporte para funciones como interpolación y pluralización.
En componentes de Astro, esta API está disponible como parte del objeto global Astro
como Astro.locals.t
:
También puedes usar la API en endpoints, donde el objeto locals
está disponible como parte del contexto del endpoint:
Renderizar una string de UI
Renderiza strings de UI utilizando la función locals.t()
.
Esta es una instancia de la función t()
de i18next, que toma una clave de cadena de UI como su primer argumento y devuelve la traducción correspondiente para el idioma actual.
Por ejemplo, dado un archivo de traducción personalizado con el siguiente contenido:
La primera string de UI se puede renderizar pasando 'link.astro'
a la función t()
:
La segunda string de UI utiliza la sintaxis de interpolación de i18next para el marcador {{feature}}
.
El valor de feature
debe establecerse en un objeto de opciones pasado como segundo argumento a t()
:
Ver la documentación de i18next para obtener más información sobre cómo usar la función t()
con interpolación, formato y más.
APIs avanzadas
t.all()
La función locals.t.all()
devuelve un objeto que contiene todas las strings de UI disponibles para el idioma actual.
t.exists()
Para comprobar si una clave de traducción existe para un idioma, utiliza la función locals.t.exists()
con la clave de traducción como primer argumento.
Pasa un segundo argumento opcional si necesitas anular el idioma actual.
Ver la referencia de exists()
en la documentación de i18next para obtener más información.
t.dir()
La función locals.t.dir()
devuelve la dirección del texto del idioma actual o de un idioma específico.
Ver la referencia de dir()
en la documentación de i18next para obtener más información.
Acceder al idioma actual
Puedes usar Astro.currentLocale
para leer el idioma actual en componentes .astro
.
El siguiente ejemplo lee el idioma actual y lo utiliza con la función getRelativeLocaleUrl()
para generar un enlace a una página Acerca de en el idioma actual: