Intégration Astro
Utilisez ai-i18n-tools avec Astro dans deux configurations courantes : les sites de documentation Astro Starlight et les sites marketing ou d'applications Astro simples. Les deux utilisent des documents (translate-docs) pour le contenu des pages ; les sites Astro simples combinent souvent cela avec des chaînes d'interface utilisateur (extract / translate-ui) pour les chaînes t() dans le frontmatter et les données partagées.
Voir aussi Chaînes d'interface utilisateur, Documents et les exemples exécutables ci-dessous.
Astro Starlight
Utilisez init -t ui-starlight et docsOutput.style: "astro-starlight" pour les sites de documentation Astro Starlight. Le préréglage est un alias pour doc-system avec un localeSubpath vide — les pages traduites se retrouvent sous src/content/docs/<locale>/ à côté de l'arborescence de la locale source. sourceLocale peut être n'importe quelle langue.
Démarrage rapide
ai-i18n-tools init -t ui-starlight -P cheaperinference
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths)
pnpm run i18n:sync # or: ai-i18n-tools sync
pnpm dev # Starlight dev server (project-specific script)Disposition de la page
Le markdown et le MDX anglais se trouvent à la racine du contenu de Starlight (généralement src/content/docs/). Les copies traduites sont écrites à côté de l'arborescence source :
src/content/docs/quick-start.md → src/content/docs/de/quick-start.md
src/content/docs/guide/setup.mdx → src/content/docs/fr/guide/setup.mdxConfigurez un bloc docs[] :
{
"contentPaths": ["src/content/docs/"],
"outputDir": "src/content/docs",
"docsOutput": {
"style": "astro-starlight",
"docsRoot": "src/content/docs"
}
}Pointez contentPaths vers les fichiers et répertoires .md / .mdx écrits en sourceLocale. Cette langue peut être n'importe quelle langue. Définissez docsRoot sur le même dossier que Starlight utilise comme racine de contenu.
Les remplacements d'interface utilisateur de Starlight peuvent utiliser src/content/i18n/en.json avec jsonPathTemplate dans un bloc docs[] séparé si nécessaire — voir Documents — initialiser pour la documentation.
Starlight fournit des chaînes d'interface utilisateur intégrées pour de nombreuses langues (libellés de navigation, espace réservé de recherche, table des matières, etc.). Il n'y a pas de pipeline shell/thème distinct à configurer — utilisez translate-docs uniquement pour le contenu des pages. Pour les autres frameworks, consultez Traduction du shell du framework.
Les label de la barre latérale explicites, le title du site et les social[].label dans astro.config.mjs sont des littéraux anglais que cet outil ne traduit pas. Préférez les entrées slug afin que l'étiquette provienne du frontmatter traduit de la page (title). Un groupe ou un lien externe qui nécessite sa propre formulation utilise la carte translations par locale de Starlight (label pour la locale par défaut, translations['pt-BR'] pour les autres). social[].label n'a pas de champ de traductions dans le schéma Starlight actuel ; il reste tel quel. Voir Barre latérale de Starlight et examples/astro-docs/astro.config.mjs, qui utilise des entrées slug.
Activer l'i18n dans un site existant
La configuration initiale s'appuie sur l'invite de Ajouter l'i18n à un site web ou un site de documentation. La liste de contrôle ci-dessous correspond au même travail effectué manuellement.
localesdans la configuration Starlight, y compris une entréerootlorsque l'anglais ne doit pas être préfixé (labeletlangrequis).defaultLocale: 'root'lorsque la langue par défaut est cette locale racine. N'omettezdefaultLocaleque si la valeur par défaut de Starlight correspond déjà.- Les pages anglaises restent dans
src/content/docs/;translate-docsécritsrc/content/docs/<locale>/. targetLocalesaligné avec les clés de locale non-racine (attention à la casse : les clés de répertoire Starlight sont souvent en minuscules, commept-br).
Exemple de projet
examples/astro-docs — Sources anglaises à src/content/docs/, traductions validées sous src/content/docs/<locale>/, locale RTL (ar), et traduction basée sur le glossaire. Exécutez pnpm dev sur le port 3050.
Astro simple (sites marketing et d'applications)
Pour les sites marketing ou d'applications Astro statiques (pas Starlight), associez le routage i18n intégré d'Astro à ai-i18n-tools. La configuration initiale s'appuie sur l'invite de Ajouter l'i18n à un site web ou un site de documentation. L'implémentation de référence est examples/astro-website : l'anglais à /, les locales cibles à /{locale}/.
La plupart des équipes utilisent un hybride de deux pipelines sur la même page :
| Pipeline | À utiliser pour | Commandes | Sortie |
|---|---|---|---|
| HTML des pages | Titres, paragraphes, libellés de navigation, tableaux intégrés dans le corps du modèle | translate-docs | Un src/pages/{locale}/index.astro par localisation |
Chaînes d'interface utilisateur (t()) | Données de frontmatter, étiquettes d'onglets, tableaux partagés | extract → translate-ui | public/locales/{locale}.json (chaîne de la langue source comme clé) |
Démarrage rapide
ai-i18n-tools init -t ui-astro-website -P ollama
# enable features.translateDocs and add a docs[] block for page HTML (see below)
pnpm run i18n:sync
pnpm devGénérer l'extraction de l'interface utilisateur avec init -t ui-astro-website -P ollama, puis fusionner dans un bloc docs[] lorsque vous traduisez également le HTML de la page :
{
"features": {
"translateUIStrings": true,
"translateDocs": true
},
"ui": {
"sourceRoots": ["src/"],
"stringsJson": "public/locales/strings.json",
"flatOutputDir": "public/locales/"
},
"docs": [{
"contentPaths": ["src/pages/index.astro"],
"outputDir": "src/pages",
"docsOutput": {
"style": "astro-starlight",
"docsRoot": "src/pages"
},
"addFrontmatter": false
}]
}Maintenez trois listes alignées lorsque vous ajoutez ou supprimez une langue : targetLocales dans ai-i18n-tools.config.json, i18n.locales dans astro.config.mjs (Astro utilise des codes de route en minuscules tels que pt-br), et ui-languages.json (via generate-ui-languages). Les noms de fichiers du bundle plat utilisent la casse de la configuration (pt-BR.json) ; mappez la route pt-br d'Astro à ce fichier via votre champ code de manifeste.
Résolvez t('…') au moment de la construction en recherchant le littéral de la langue source comme clé — voir examples/astro-website/src/i18n/t.ts. sourceLocale peut être n'importe quelle langue. L'exemple utilise l'anglais. Vous n'avez pas besoin de ai-i18n-tools/runtime ou d'i18next pour un site statique, sauf si vous ajoutez des îles clientes qui changent de langue après le chargement.
Exemple de projet
examples/astro-website — page de destination hybride avec HTML via translate-docs et étiquettes d'onglets de capture d'écran via t() + translate-ui.
Exemples de projets
| Projet | Cas d'utilisation | Port |
|---|---|---|
| examples/astro-docs | Documentation Starlight | 3050 |
| examples/astro-website | Site marketing Astro simple (hybride HTML + t()) | (voir README) |
Compare examples/astro-docs avec examples/docusaurus-docs — contenu de tutoriel similaire, style de sortie Docusaurus au lieu de Starlight.