Internationalisation (i18n)

Cette annexe rassemble les recherches et essais menés pour rendre le site multilingue (français et anglais), et explique les choix qui en découlent.

Comment Starlight gère les langues

Les langues sont déclarées dans astro.config.mjs. Ici, le français est la langue racine : ses pages restent à la racine du site, et l’anglais est placé sous /en/.

defaultLocale: 'root',
locales: {
  root: { label: 'Français', lang: 'fr' },
  en: { label: 'English', lang: 'en' },
},

Chaque langue a son dossier, et une page est reliée à sa traduction par un chemin identique :

src/content/docs/guides/getting-started.md      →  /guides/getting-started/
src/content/docs/en/guides/getting-started.md   →  /en/guides/getting-started/

Starlight fournit ensuite, sans autre réglage :

Fonction	Comportement
Sélecteur de langue	Ajouté dans l’en-tête dès qu’il y a deux langues ; mène à la même page dans l’autre langue
Interface	Traduite (« Rechercher » / « Search »…) ; le français et l’anglais sont fournis
Page non traduite	La version anglaise affiche le contenu français, avec un bandeau d’avertissement
Recherche	Séparée par langue
Référencement	Balises `hreflang` reliant les traductions

Restent manuels : les libellés des groupes de la barre latérale (option translations), les liens internes des pages anglaises (qui doivent commencer par /en/), et les captures d’écran.

Les adresses : des noms de fichiers en anglais

Puisque les traductions sont reliées par leur chemin, les noms de fichiers et de dossiers sont les mêmes dans toutes les langues, et ils apparaissent dans les adresses. Starlight ne propose pas de traduire les adresses : un fichier anglais renommé n’est plus reconnu comme une traduction.

Les noms ont donc été passés en anglais (demarrage.md → getting-started.md, dossier comprendre/ → concepts/…) avant la mise en ligne, tant qu’aucun lien externe ne pointait vers les anciennes adresses. C’est la pratique la plus courante des documentations multilingues : un mot anglais est compris par davantage de lecteurs, quelle que soit leur langue.

Côté CMS : le problème de l’emplacement des traductions

Decap CMS

Decap CMS sait gérer les traductions d’une même page (champs par langue, édition côte à côte), avec trois façons de ranger les fichiers. L’examen de son code source (decap-cms-core, fichier lib/i18n.ts) montre que la structure par dossiers place la langue dans le dossier de la collection :

Decap      : src/content/docs/guides/en/getting-started.md
Starlight  : src/content/docs/en/guides/getting-started.md

Les deux ne sont pas compatibles. Decap n’a pas non plus d’option pour ranger la langue par défaut sans dossier.

Essai : une collection unique pour toute la documentation

Avec une seule collection couvrant tout src/content/docs/, la structure de Decap aboutirait au bon emplacement. Un essai de cette « collection imbriquée » (fonction en bêta) a montré :

les sections apparaissent sous forme d’arbre, avec les noms de dossiers bruts ;
à la création, un champ Emplacement est à saisir à la main : une faute de frappe crée une nouvelle section ;
chaque nouvelle page devient un dossier avec un index.md ; un emplacement laissé sur guides crée la page d’accueil de la section au lieu d’une nouvelle page ;
le français devrait lui aussi avoir son dossier (/fr/…), ce qui changerait toutes les adresses.

Trop de risques d’erreur pour des rédacteurs : cette piste a été écartée.

Sveltia CMS

Sveltia CMS résout exactement ce problème : la langue par défaut peut être rangée sans dossier (omit_default_locale_from_file_path), et un marqueur {{locale}} permet de placer la langue où l’on veut dans le chemin. Sa documentation recommande d’ailleurs cette configuration pour Starlight. Mais Sveltia ne prend pas en charge Bitbucket, et ne prévoit pas de le faire.

Les options comparées

Option	Édition côte à côte	Français à la racine	Bitbucket	Verdict
Sveltia CMS	✅	✅	❌	Écarté (Bitbucket)
Decap, collection unique	✅ (en théorie)	❌	✅	Écarté (ergonomie, adresses)
Decap, une collection par section et par langue	❌	✅	✅	Retenu
Traductions hors du CMS	❌	✅	✅	Possible en complément

La solution retenue

Une collection Decap par section et par langue : « Guides » et « Guides (EN) », etc. Une page et sa traduction s’éditent séparément ; la procédure est décrite dans Éditer avec Decap CMS.
Un champ « Nom du fichier » dans le formulaire de création : le rédacteur y saisit un nom en anglais (par exemple install), utilisé pour nommer le fichier quelle que soit la langue du titre. Sans lui, Decap tirerait le nom du titre, en français dans la collection française.
Le français reste la langue racine : aucune adresse existante ne change.

Points d’attention

Rien ne garantit que les deux versions d’une page restent alignées : une modification de la page française doit être reportée à la main dans la page anglaise.
Le « Nom du fichier » d’une traduction doit être identique à celui de la page d’origine, sinon la page n’est pas reconnue comme traduction.
L’interface de Decap elle-même reste en français, quelle que soit la langue éditée.