Saltearse al contenido
Starlight

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

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

  2. 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/
            • …

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

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

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

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

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


export default defineConfig({
  integrations: [
    starlight({
      title: 'Mi Documentación',
      title: {
        es: 'Mi Documentación',
        'zh-CN': '我的文档',
      },
      defaultLocale: 'es',
      locales: {
        es: { label: 'Español' },
        'zh-cn': { label: '简体中文', lang: 'zh-CN' },
      },
    }),
  ],
});

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, catalán, 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.

  1. 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() }),
      i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
    };

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

  3. 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.ctrlKey": "Ctrl",
      "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",
      "builtWithStarlight.label": "Built with 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:

    {
      "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:

src/content/config.ts
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.

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:

example.astro
<p dir={Astro.locals.t.dir()}>
  {Astro.locals.t('404.text')}
</p>

También puedes usar la API en endpoints, donde el objeto locals está disponible como parte del contexto del endpoint:

src/pages/404.ts
export const GET = (context) => {
  return new Response(context.locals.t('404.text'));
};

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:

src/content/i18n/en.json
{
  "link.astro": "Astro documentation",
  "link.astro.custom": "Astro documentation for {{feature}}"
}

La primera string de UI se puede renderizar pasando 'link.astro' a la función t():

src/components/Example.astro
<a href="https://docs.astro.build/">
  {Astro.locals.t('link.astro')}
</a>
<!-- Renderiza: <a href="...">Astro documentation</a> -->

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():

src/components/Example.astro
<a href="https://docs.astro.build/en/guides/astro-db/">
  {Astro.locals.t('link.astro.custom', { feature: 'Astro DB' })}
</a>
<!-- Renderiza: <a href="...">Astro documentation for Astro DB</a> -->

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.

src/components/Example.astro
---
const allStrings = Astro.locals.t.all();
//    ^
//    {
//      "skipLink.label": "Skip to content",
//      "search.label": "Search",
//      …
//    }
---

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.

src/components/Example.astro
---
const keyExistsInCurrentLocale = Astro.locals.t.exists('a.key');
//    ^ true
const keyExistsInFrench = Astro.locals.t.exists('another.key', { lng: 'fr' });
//    ^ false
---

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.

src/components/Example.astro
---
const currentDirection = Astro.locals.t.dir();
//    ^
//    'ltr'
const arabicDirection = Astro.locals.t.dir('ar');
//    ^
//    'rtl'
---

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:

src/components/AboutLink.astro
---
import { getRelativeLocaleUrl } from 'astro:i18n';
---


<a href={getRelativeLocaleUrl(Astro.currentLocale ?? 'en', 'about')}>Acerca</a>