Intégration Docusaurus

Utilisez init -t ui-docusaurus et docsOutput.style: "docusaurus" pour les sites de documentation Docusaurus. Le préréglage génère un bloc docs[] avec docusaurusCatalogDir afin que translate-docs puisse traduire à la fois le markdown de la page et le JSON de l'interface Docusaurus en une seule commande.

Voir aussi Documents, la démo exécutable examples/docusaurus-docs, et examples/nextjs-app pour une application Next.js combinée avec des documents Docusaurus imbriqués, un fichier README plat et des ressources SVG.

Démarrage rapide

ai-i18n-tools init -t ui-docusaurus [-P <provider>]
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths, docusaurusCatalogDir)
pnpm run i18n:sync   # or: ai-i18n-tools sync
cd docs-site && pnpm build   # or: cd examples/docusaurus-docs && pnpm build

Activez features.translateDocs et définissez docs[].docusaurusCatalogDir lorsque vous traduisez à la fois les pages de documentation et l'interface du site (barre de navigation, pied de page, chaînes de thème). Exécutez docusaurus write-translations dans votre projet Docusaurus lorsque vous mettez à niveau @docusaurus/* ou modifiez les étiquettes de la barre de navigation/pied de page/thème — puis réexécutez translate-docs ou sync afin que le JSON de l'interface soit traduit dans chaque dossier de locale.

Disposition de la page

Le markdown et le MDX anglais se trouvent dans le dossier docs/ de votre Docusaurus (par exemple docs-site/docs/). Les copies traduites sont écrites dans l'arborescence de contenu du plugin de chaque locale :

docs-site/docs/getting-started.md
  →  docs-site/i18n/de/docusaurus-plugin-content-docs/current/getting-started.md
docs-site/docs/guide/quick-start.md
  →  docs-site/i18n/fr/docusaurus-plugin-content-docs/current/guide/quick-start.md

Configurez un bloc docs[] :

{
  "contentPaths": ["docs-site/docs/"],
  "outputDir": "docs-site/i18n",
  "docusaurusCatalogDir": "docs-site/i18n/en",
  "addFrontmatter": true,
  "docsOutput": {
    "style": "docusaurus",
    "docsRoot": "docs-site/docs"
  }
}

Pointez contentPaths vers vos fichiers et répertoires .md / .mdx anglais. Définissez docsRoot sur le même dossier que Docusaurus utilise comme racine de contenu. Définissez outputDir sur le parent de chaque dossier de locale sous i18n/.

Connectez l'internationalisation de Docusaurus : maintenez targetLocales dans ai-i18n-tools.config.json aligné avec le tableau locales dans docusaurus.config.js. Chaque localeConfigs[locale].path doit correspondre au nom du dossier sous i18n/ (par exemple path: "fr" pour i18n/fr/).

Chaînes de l'interface (write-translations)

La barre de navigation, le pied de page, l'espace réservé à la recherche et les autres étiquettes de thème/plugin de Docusaurus ne sont pas extraits du markdown. Exécutez docusaurus write-translations dans votre projet Docusaurus pour générer des catalogues JSON sous le dossier de locale par défaut (généralement i18n/en/). Ensuite, pointez docs[].docusaurusCatalogDir vers ce dossier :

{
  "features": {
    "translateDocs": true
  },
  "docs": [
    {
      "description": "Docusaurus pages + shell JSON",
      "contentPaths": ["docs-site/docs/"],
      "outputDir": "docs-site/i18n",
      "docusaurusCatalogDir": "docs-site/i18n/en",
      "docsOutput": {
        "style": "docusaurus",
        "docsRoot": "docs-site/docs"
      }
    }
  ]
}

Lorsque docusaurusCatalogDir est défini et features.translateDocs est activé, translate-docs traduit les deux :

• Pages de documentation — markdown/MDX de contentPaths vers i18n/<locale>/docusaurus-plugin-content-docs/current/
• JSON de l'interface — catalogues de la barre de navigation, du pied de page et du thème/plugin de i18n/en/ vers les dossiers de locale frères

Ne placez pas le JSON de l'interface Docusaurus dans json[] ; utilisez plutôt docs[].docusaurusCatalogDir avec Documents.

Exemple de projet

examples/docusaurus-docs — sources anglaises à docs/, traductions validées sous i18n/<locale>/docusaurus-plugin-content-docs/current/, plus JSON de shell traduit. Exécutez pnpm start sur le port 3100 (build + serve) pour que le menu déroulant des langues fonctionne ; utilisez pnpm dev pour le rechargement à chaud en anglais uniquement.

Pour les chaînes d'interface utilisateur, la traduction SVG et un fichier README plat dans la même disposition de dépôt, voir examples/nextjs-app (docs-site/ imbriqué sur le port 3040).