Aller au contenu
Starlight

Internationalisation (i18n)

Starlight offre une prise en charge intégrée des sites multilingues, y compris le routage, le contenu de repli et la prise en charge complète des langues de droite à gauche (RTL).

Configurer i18n

  1. Indiquez à Starlight les langues que vous prenez en charge en passant locales et defaultLocale à l’intégration Starlight :

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

    export default defineConfig({
      integrations: [
        starlight({
          title: 'My Docs',
          // Définit l'anglais comme langue par défaut pour ce site.
          defaultLocale: 'en',
          locales: {
            // Docs en anglais dans `src/content/docs/en/`
            en: {
              label: 'English',
            },
            // Docs en chinois simplifié dans `src/content/docs/zh-cn/`
            'zh-cn': {
              label: '简体中文',
              lang: 'zh-CN',
            },
            // Docs en arabe dans `src/content/docs/ar/`
            ar: {
              label: 'العربية',
              dir: 'rtl',
            },
          },
        }),
      ],
    });

    Votre defaultLocale sera utilisé pour le contenu de repli et les étiquettes de l’interface utilisateur, donc choisissez la langue dans laquelle vous êtes le plus susceptible de commencer à écrire du contenu, ou pour laquelle vous avez déjà du contenu.

  2. Créez un répertoire pour chaque langue dans src/content/docs/. Par exemple, pour la configuration montrée ci-dessus, créez les dossiers suivants :

    • Répertoiresrc/
      • Répertoirecontent/
        • Répertoiredocs/
          • Répertoirear/
            • …
          • Répertoireen/
            • …
          • Répertoirezh-cn/
            • …

  3. Vous pouvez maintenant ajouter des fichiers de contenu dans vos répertoires de langues. Utilisez le même nom de fichier pour associer les pages d’une langue à l’autre et profiter de l’ensemble des fonctionnalités i18n de Starlight, y compris le contenu de repli, les avis de traduction, etc.

    Par exemple, créez ar/index.md et en/index.md pour représenter la page d’accueil en arabe et en anglais respectivement.

Pour les scénarios i18n plus avancés, Starlight prend également en compte la configuration de l’internationalisation à l’aide de l’option de configuration i18n d’Astro.

Utiliser une locale racine

Vous pouvez utiliser une locale « racine » pour servir une langue sans aucun préfixe i18n dans son chemin. Par exemple, si l’anglais est votre locale racine, le chemin d’une page en anglais ressemblera à /about au lieu de /en/about.

Pour définir une locale racine, utilisez la clé root dans votre configuration locales. Si la locale racine est aussi la locale par défaut de votre contenu, supprimez defaultLocale ou donnez-lui la valeur 'root'.

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


export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      defaultLocale: 'root', // optionnel
      locales: {
        root: {
          label: 'English',
          lang: 'en', // lang est nécessaire pour les locales racine
        },
        'zh-cn': {
          label: '简体中文',
          lang: 'zh-CN',
        },
      },
    }),
  ],
});

Lorsque vous utilisez une locale racine avec la clé root, conservez les pages de cette langue directement dans src/content/docs/ au lieu d’un dossier dédié à cette langue. Par exemple, voici les fichiers de la page d’accueil pour l’anglais et le chinois en utilisant la configuration ci-dessus :

  • Répertoiresrc/
    • Répertoirecontent/
      • Répertoiredocs/
        • index.md
        • Répertoirezh-cn/
          • index.md

Sites monolingues

Par défaut, Starlight est un site monolingue (anglais). Pour créer un site monolingue dans une autre langue, définissez-la comme root dans votre configuration locales :

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


export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      locales: {
        root: {
          label: '简体中文',
          lang: 'zh-CN',
        },
      },
    }),
  ],
});

Cela vous permet de remplacer la langue par défaut de Starlight sans activer d’autres fonctions d’internationalisation pour les sites multilingues, telles que le sélecteur de langue.

Contenu de repli

Starlight s’attend à ce que vous créiez des pages équivalentes dans toutes vos langues. Par exemple, si vous avez un fichier en/about.md, créez un about.md pour chaque autre langue que vous supportez. Cela permet à Starlight de fournir un contenu de repli automatique pour les pages qui n’ont pas encore été traduites.

Si une traduction n’est pas encore disponible pour une langue, Starlight affichera aux lecteurs le contenu de cette page dans la langue par défaut (définie via defaultLocale). Par exemple, si vous n’avez pas encore créé de version française de votre page À propos et que votre langue par défaut est l’anglais, les visiteurs de /fr/about verront le contenu anglais de /en/about avec un avis indiquant que cette page n’a pas encore été traduite. Cela vous permet d’ajouter du contenu dans votre langue par défaut et de le traduire progressivement lorsque vos traducteurs en ont le temps.

Traduire le titre du site

Par défaut, Starlight utilisera le même titre de site pour toutes les langues. Si vous avez besoin de personnaliser le titre pour chaque langue, vous pouvez passer un objet à title dans les options de Starlight :

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


export default defineConfig({
  integrations: [
    starlight({
      title: 'Ma documentation',
      title: {
        fr: 'Ma documentation',
        'zh-CN': '我的文档',
      },
      defaultLocale: 'fr',
      locales: {
        fr: { label: 'Français' },
        'zh-cn': { label: '简体中文', lang: 'zh-CN' },
      },
    }),
  ],
});

Traduire l’interface utilisateur de Starlight

En plus d’héberger des fichiers de contenu traduits, Starlight vous permet de traduire les chaînes de l’interface utilisateur par défaut (par exemple, l’en-tête “Sur cette page” dans la table des matières) afin que vos lecteurs puissent découvrir votre site entièrement dans la langue sélectionnée.

Les textes de l’interface utilisateur traduits en allemand, anglais, arabe, chinois, chinois (Taïwan), coréen, danois, espagnol, français, galicien, hébreu, hindi, indonésien, italien, japonais, néerlandais, norvégien bokmål, persan, polonais, portugais, roumain, russe, slovaque, suédois, tchèque, turc, ukrainien et vietnamien sont disponibles prêts à l’emploi, et nous acceptons les contributions pour ajouter d’autres langues par défaut.

Vous pouvez fournir des traductions pour les langues supplémentaires que vous supportez - ou remplacer nos étiquettes par défaut - via la collection de contenus i18n.

  1. Configurez la collection de contenus i18n dans src/content/config.ts si elle n’est pas déjà configurée :

    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() }),
    };

  2. Créez un fichier JSON dans src/content/i18n/ pour chaque locale supplémentaire pour laquelle vous voulez fournir des chaînes de traduction pour l’interface utilisateur. Par exemple, cela ajouterait des fichiers de traduction pour l’arabe et le chinois simplifié :

    • Répertoiresrc/
      • Répertoirecontent/
        • Répertoirei18n/
          • ar.json
          • zh-CN.json

  3. Ajoutez des traductions pour les clés que vous souhaitez traduire dans les fichiers JSON. Traduire uniquement les valeurs, en laissant les clés en anglais (e.g. "search.label": "Buscar").

    Voici les valeurs anglaises par défaut des chaînes de caractères existantes avec lesquelles Starlight est livré :

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

    Les blocs de code de Starlight fonctionnent grâce à la librairie Expressive Code. Vous pouvez définir des traductions pour les textes de l’interface utilisateur utilisés dans le même fichier JSON en utilisant les clés expressiveCode :

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

    La module de recherche de Starlight’s s’appuie sur la librairie Pagefind. Vous pouvez définir des traductions pour l’interface utilisateur de Pagefind dans le même fichier JSON en utilisant les clés 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]..."
    }

Étendre le schéma de traduction

Ajoutez des clés personnalisées aux dictionnaires de traduction de votre site en définissant extend dans les options de i18nSchema(). Dans l’exemple suivant, une nouvelle clé optionnelle custom.label est ajoutée aux clés par défaut :

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(),
      }),
    }),
  }),
};

Consultez « Définir un schéma de collection de contenus » dans la documentation d’Astro pour en savoir plus sur les schémas de collection de contenus.

Utiliser les traductions de l’interface utilisateur

Vous pouvez accéder aux chaînes de l’interface utilisateur intégrées à Starlight ainsi qu’aux chaînes de l’interface utilisateur définies par l’utilisateur, et celles fournies par les modules d’extension via une API unifiée utilisant i18next. Cela inclut le support de fonctionnalités telles que l’interpolation et la pluralisation.

Dans les composants Astro, cette API est disponible via l’objet global Astro sous le nom Astro.locals.t :

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

Vous pouvez également utiliser l’API dans les points de terminaison, où l’objet locals est disponible dans le cadre du contexte du point de terminaison:

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

Afficher une chaîne de l’interface utilisateur

Affichez une chaîne de l’interface utilisateur en utilisant la fonction locals.t(). C’est une instance de la fonction t() d’i18next, qui prend une clé de chaîne d’interface utilisateur en premier argument et renvoie la traduction correspondante pour la langue actuelle.

Par exemple, étant donné un fichier de traduction personnalisé avec le contenu suivant :

src/content/i18n/fr.json
{
  "link.astro": "Documentation d'Astro",
  "link.astro.custom": "Documentation d'Astro pour {{feature}}"
}

La première chaîne d’interface utilisateur peut être affichée en passant 'link.astro' à la fonction t() :

src/components/Exemple.astro
<a href="https://docs.astro.build/">
  {Astro.locals.t('link.astro')}
</a>
<!-- Affiche: <a href="...">Documentation d'Astro</a> -->

La deuxième chaîne d’interface utilisateur utilise la syntaxe d’interpolation d’i18next pour le paramètre {{feature}}. La valeur de feature doit être définie dans un objet d’options passé en tant que deuxième argument à t() :

src/components/Exemple.astro
<a href="https://docs.astro.build/en/guides/astro-db/">
  {Astro.locals.t('link.astro.custom', { feature: 'Astro DB' })}
</a>
<!-- Affiche: <a href="...">Documentation d'Astro pour Astro DB</a> -->

Consultez la documentation d’i18next pour plus d’informations sur l’utilisation de la fonction t() avec l’interpolation, le formatage, et plus encore.

APIs avancées

t.all()

La fonction locals.t.all() renvoie un objet contenant toutes les chaînes d’interface utilisateur disponibles pour la langue actuelle.

src/components/Exemple.astro
---
const allStrings = Astro.locals.t.all();
//    ^
//    {
//      "skipLink.label": "Aller au contenu",
//      "search.label": "Rechercher",
//      …
//    }
---

t.exists()

Pour vérifier si une clé de traduction existe pour une langue, utilisez la fonction locals.t.exists() avec la clé de traduction comme premier argument. Passez un deuxième argument facultatif si vous avez besoin de re-définir la langue actuelle.

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

Consultez la référence pour exists() dans la documentation d’i18next pour plus d’informations.

t.dir()

La fonction locals.t.dir() renvoie la direction du texte de la langue actuelle ou d’une langue spécifique.

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

Consultez la référence pour dir() dans la documentation d’i18next pour plus d’informations.

Accès aux paramètres régionaux

Vous pouvez utiliser Astro.currentLocale pour lire les paramètres régionaux et linguistiques actuels dans les composants .astro.

L’exemple suivant lit les paramètres régionaux actuels et les utilise avec la fonction getRelativeLocaleUrl() pour générer un lien vers une page d’information dans la langue actuelle :

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


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