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 y defaultLocale a la integración de Starlight:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
	integrations: [
		starlight({
			title: 'Mis Docs',
			// Establece el inglés como el idioma predeterminado para este sitio.
			defaultLocale: 'en',
			locales: {
				// Documentación en inglés en `src/content/docs/en/`
				en: {
					label: 'English',
				},
				// Chino simplificado en `src/content/docs/zh/`
				zh: {
					label: '简体中文',
					lang: 'zh-CN',
				},
				// Documentación en árabe en `src/content/docs/ar/`
				ar: {
					label: 'العربية',
					dir: 'rtl',
				},
			},
		}),
	],
});

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/
    …
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 y en/index.md para representar la página de inicio en árabe e inglés, respectivamente.

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'.

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
	integrations: [
		starlight({
			title: 'My Docs',
			defaultLocale: 'root', // opcional
			locales: {
				root: {
					label: 'English',
					lang: 'en', // lang es obligatorio para los locales raíz
				},
				zh: {
					label: '简体中文',
					lang: 'zh-CN',
				},
			},
		}),
	],
});

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/
    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:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
	integrations: [
		starlight({
			title: 'Mis docs',
			locales: {
				root: {
					label: '简体中文',
					lang: 'zh-CN',
				},
			},
		}),
	],
});

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 la UI de Starlight

Starlight proporciona de forma predeterminada traducciones para los textos utilizados en la UI al inglés, checo, francés, alemán, italiano, japonés, holandés, portugués, danés, español, turco, árabe, noruego, farsi y chino simplificado. También damos la bienvenida a contribuciones para agregar más idiomas predeterminados.

Configura la colección de datos i18n en src/content/config.ts si aún no está configurada:

// src/content/config.ts
import { defineCollection } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
	docs: defineCollection({ schema: docsSchema() }),
	i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
};

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:

{
	"skipLink.label": "Skip to content",
	"search.label": "Search",
	"search.shortcutLabel": "(Press / to Search)",
	"search.cancelLabel": "Cancel",
	"search.devWarning": "Search is only available in production builds. \nTry building and previewing the site to test it out locally.",
	"themeSelect.accessibleLabel": "Select theme",
	"themeSelect.dark": "Dark",
	"themeSelect.light": "Light",
	"themeSelect.auto": "Auto",
	"languageSelect.accessibleLabel": "Select language",
	"menuButton.accessibleLabel": "Menu",
	"sidebarNav.accessibleLabel": "Main",
	"tableOfContents.onThisPage": "On this page",
	"tableOfContents.overview": "Overview",
	"i18n.untranslatedContent": "This content is not available in your language yet.",
	"page.editLink": "Edit page",
	"page.lastUpdated": "Last updated:",
	"page.previousLink": "Next",
	"page.nextLink": "Previous"
}

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:

{
	"pagefind.clear_search": "Clear",
	"pagefind.load_more": "Load more results",
	"pagefind.search_label": "Search this site",
	"pagefind.filters_label": "Filters",
	"pagefind.zero_results": "No results for [SEARCH_TERM]",
	"pagefind.many_results": "[COUNT] results for [SEARCH_TERM]",
	"pagefind.one_result": "[COUNT] result for [SEARCH_TERM]",
	"pagefind.alt_search": "No results for [SEARCH_TERM]. Showing results for [DIFFERENT_TERM] instead",
	"pagefind.search_suggestion": "No results for [SEARCH_TERM]. Try one of the following searches:",
	"pagefind.searching": "Searching for [SEARCH_TERM]..."
}