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

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

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 :
- Directorysrc/
  - Directorycontent/
    Directorydocs/
    Directoryar/
    …
    Directoryen/
    …
    Directoryzh/
    …
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.

Utiliser une racine locale

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

Pour définir une racine locale, utilisez la clé root dans votre configuration locales. Si la racine locale 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 de la racine
				},
				zh: {
					label: '简体中文',
					lang: 'zh-CN',
				},
			},
		}),
	],
});

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

Directorysrc/
- Directorycontent/
  - Directorydocs/
    index.md
    Directoryzh/
    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 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 chaînes d’interface utilisateur traduites en anglais, arabe, allemand, chinois simplifié, danois, espagnol, français, italien, japonais, néerlandais, norvégien, portugais, tchèque et turc sont fournies d’entrée, 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 données i18n.

Configurez la collection de données 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() }),
};

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é :
- Directorysrc/
  - Directorycontent/
    Directoryi18n/
    ar.json
    zh-CN.json

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").

Il s’agit des valeurs anglaises par défaut des chaînes de caractères existantes avec lesquelles Starlight est livré :

{
	"skipLink.label": "Aller au contenu",
	"search.label": "Rechercher",
	"search.shortcutLabel": "(Presser / pour rechercher)",
	"search.cancelLabel": "Annuler",
	"search.devWarning": "La recherche est disponible uniquement en mode production. \nEssayez de construire puis de prévisualiser votre site pour tester la recherche localement.",
	"themeSelect.accessibleLabel": "Selectionner le thème",
	"themeSelect.dark": "Sombre",
	"themeSelect.light": "Clair",
	"themeSelect.auto": "Auto",
	"languageSelect.accessibleLabel": "Selectionner la langue",
	"menuButton.accessibleLabel": "Menu",
	"sidebarNav.accessibleLabel": "principale",
	"tableOfContents.onThisPage": "Sur cette page",
	"tableOfContents.overview": "Vue d’ensemble",
	"i18n.untranslatedContent": "Ce contenu n’est pas encore disponible dans votre langue.",
	"page.editLink": "Modifier cette page",
	"page.lastUpdated": "Dernière mise à jour :",
	"page.previousLink": "Précédent",
	"page.nextLink": "Suivant",
	"404.text": "Page non trouvée. Vérifiez l’URL ou essayez d’utiliser la barre de recherche."
}

La module de recherche de Starlight’s est propulsé par la librairie Pagefind. Vous pouvez défiinr les tradctions pour l’interface de Pagefinddans le même fichier JSON file en utilisant les propriétés pagefind :

{
	"pagefind.clear_search": "Effacer",
	"pagefind.load_more": "Charger plus de résultats",
	"pagefind.search_label": "Rechercher sur ce site",
	"pagefind.filters_label": "Filtres",
	"pagefind.zero_results": "Pas de résultat pour [SEARCH_TERM]",
	"pagefind.many_results": "[COUNT] resultats pour [SEARCH_TERM]",
	"pagefind.one_result": "[COUNT] resultat pour [SEARCH_TERM]",
	"pagefind.alt_search": "Pas de résultats pour [SEARCH_TERM]. Voici à la place des résultats pour [DIFFERENT_TERM].",
	"pagefind.search_suggestion": "Pas de résultats pour [SEARCH_TERM]. Essayez l'une de ces recherches :",
	"pagefind.searching": "Recherche en cours pour [SEARCH_TERM]..."
}