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:

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-cn/`
        'zh-cn': {
          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-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 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'.

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-cn': {
          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-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:

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

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, 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 en src/content/config.ts si aún no está configurada:

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() }),
  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": "Previous",
  "page.nextLink": "Next",
  "page.draft": "This content is a draft and will not be included in production builds.",
  "404.text": "Page not found. Check the URL or try using the search bar.",
  "aside.note": "Note",
  "aside.tip": "Tip",
  "aside.caution": "Caution",
  "aside.danger": "Danger",
  "fileTree.directory": "Directory"
}

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:

{
  "expressiveCode.copyButtonCopied": "Copied!",
  "expressiveCode.copyButtonTooltip": "Copy to clipboard",
  "expressiveCode.terminalWindowFallbackTitle": "Terminal window"
}

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]..."
}

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:

import { defineCollection, z } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ schema: docsSchema() }),
  i18n: defineCollection({
    type: 'data',
    schema: i18nSchema({
      extend: z.object({
        'custom.label': z.string().optional(),
      }),
    }),
  }),
};

Aprende más sobre los esquemas de colección de contenido en “Definir un esquema de colección” en la documentación de Astro.