Skip to content

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 ​

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

text
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.mdx

Configurez un bloc docs[] :

json
{
  "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.

  • locales dans la configuration Starlight, y compris une entrée root lorsque l'anglais ne doit pas être préfixé (label et lang requis).
  • defaultLocale: 'root' lorsque la langue par défaut est cette locale racine. N'omettez defaultLocale que si la valeur par défaut de Starlight correspond déjà.
  • Les pages anglaises restent dans src/content/docs/ ; translate-docs écrit src/content/docs/<locale>/.
  • targetLocales aligné avec les clés de locale non-racine (attention à la casse : les clés de répertoire Starlight sont souvent en minuscules, comme pt-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 pourCommandesSortie
HTML des pagesTitres, paragraphes, libellés de navigation, tableaux intégrés dans le corps du modèletranslate-docsUn src/pages/{locale}/index.astro par localisation
Chaînes d'interface utilisateur (t())Données de frontmatter, étiquettes d'onglets, tableaux partagésextract → translate-uipublic/locales/{locale}.json (chaîne de la langue source comme clé)

Démarrage rapide ​

bash
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 dev

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

json
{
  "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 ​

ProjetCas d'utilisationPort
examples/astro-docsDocumentation Starlight3050
examples/astro-websiteSite 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.

Publié sous licence MIT.