Skip to content

Dispositions de sortie ​

docsOutput.style contrôle l'emplacement d'écriture des fichiers Markdown traduits. Utilisez les valeurs de chaîne exactes ci-dessous dans docs[].docsOutput.style. Les alias sont des mises en page prédéfinies doc-system (ou la mise en page avec suffixe en points de Fumadocs), et non des moteurs distincts. Le chargement de la configuration peut réécrire les valeurs d'alias style en "doc-system" canoniques tout en conservant le préréglage d'origine dans stylePreset.

Définissez docs[].docsOutput.pathTemplate (Markdown/MDX) ou jsonPathTemplate (fichiers d'étiquettes JSON) pour remplacer toute mise en page intégrée. Voir les placeholders pathTemplate ci-dessous.

Aperçu de la mise en page ​

docsOutput.styleMoteurUtilisation typique
"nested"Le dossier de la locale reflète l'arborescence source complètePar défaut ; sortie i18n générique sous {outputDir}/{locale}/
"flat"Suffixe de locale dans le nom de fichier (sous-répertoires facultatifs)README, journaux de modifications, documents à la racine du dépôt, sélecteur de langue
"doc-system"Dossier de locale + localeSubpath facultatif sous docsRootGénérateurs de documents statiques personnalisés
"docusaurus"Préréglage doc-systemMise en page du plugin i18n Docusaurus
"astro-starlight"Préréglage doc-system (localeSubpath: "")Astro Starlight, pages de locale Astro simples
"vitepress"Préréglage doc-system (localeSubpath: "")Dossiers de locale VitePress à côté de l'anglais
"nextra"Préréglage doc-system (localeSubpath: "")Dossiers de locale Nextra (content/en/ → content/{locale}/)
"fumadocs"Suffixe en points (par défaut) ou doc-system lorsque fumadocsParser: "dir"Mise en page de contenu en points ou en répertoires Fumadocs

nested (par défaut) ​

docsOutput.style = "nested" (par défaut si omis) — reflète l'arborescence source sous {outputDir}/{locale}/.

text
docs/guide.md  →  i18n/de/docs/guide.md
README.md      →  i18n/de/README.md

Les chemins en dehors d'un docsRoot (lorsqu'il est défini) utilisent la même forme imbriquée.

flat ​

docsOutput.style = "flat" — écrit les fichiers traduits sous outputDir avec un suffixe de locale dans le nom de fichier. Par défaut, seul le nom de base est conservé ({outputDir}/{stem}.{locale}{extension}), de sorte que docs/guide.md et docs/other/guide.md entreraient en collision à moins que vous n'activiez flatPreserveRelativeDir.

text
README.md           →  translated-docs/README.de.md
docs/guide.md       →  translated-docs/guide.de.md   (default: basename only)

Les liens relatifs entre les pages sont réécrits automatiquement lorsque docsOutput.style = "flat" (sauf si rewriteRelativeLinks: false ou un pathTemplate personnalisé est défini). Voir Liens d'ancrage pour la gestion des #anchor entre les pages.

flat avec flatPreserveRelativeDir ​

Définissez docsOutput.flatPreserveRelativeDir sur true pour conserver les sous-répertoires source sous outputDir. Utilisez ceci lorsque vous traduisez plusieurs fichiers Markdown qui partagent des noms de base dans différents dossiers, ou lorsque les sorties plates doivent refléter une arborescence peu profonde (par exemple, README à la racine du dépôt plus docs/*.md).

text
docs/guide.md       →  translated-docs/docs/guide.de.md
docs/sub/page.md    →  translated-docs/docs/sub/page.de.md

Le réécriveur de liens plats utilise le chemin de sortie par fichier lors du calcul des préfixes de profondeur pour les URL d'actifs — voir Réécriture de liens.

doc-system ​

docsOutput.style = "doc-system" — arborescence de documentation préfixée par la locale pour les sites de documentation statiques. Les fichiers sous docsRoot sont écrits dans :

text
{outputDir}/{locale}/[localeSubpath/]{relativeToDocsRoot}

Les chemins en dehors de docsRoot utilisent par défaut la mise en page imbriquée ({outputDir}/{locale}/{relPath}).

Définissez docs[].docsOutput.docsRoot sur la racine des fichiers écrits en sourceLocale (par exemple "docs", "src/content/docs" ou "content/en" lorsque l'anglais est la source). sourceLocale peut être n'importe quelle langue. Lorsque docsOutput.style = "doc-system", vous devez définir localeSubpath explicitement (utilisez un alias ci-dessous pour les préréglages). Utilisez localeSubpath: "" lorsque les pages traduites se trouvent directement sous {outputDir}/{locale}/ (style Starlight).

Le JSON de l'interface Docusaurus depuis docusaurusCatalogDir et les autres artefacts JSON sous les préréglages du système de documentation suivent la même structure de dossiers que le markdown. Avec style: "flat", les fichiers d'étiquettes JSON utilisent toujours la forme imbriquée à moins que vous ne définissiez jsonPathTemplate.

Alias du système de documentation ​

Alias (même moteur doc-system, préréglage localeSubpath et valeurs par défaut) :

  • docsOutput.style = "docusaurus" — localeSubpath utilise par défaut docusaurus-plugin-content-docs/current (mise en page du plugin i18n de Docusaurus).
  • docsOutput.style = "astro-starlight" — localeSubpath utilise par défaut "" ; localePathLowercase utilise par défaut true. Pages traduites sous {outputDir}/{locale}/, correspondant à Starlight lorsque la locale source se trouve à la racine du contenu et outputDir est égal à docsRoot. Également utilisé pour les pages de locale Astro simples (src/pages/index.astro → src/pages/{locale}/index.astro) — voir pages de site web Astro.
  • docsOutput.style = "vitepress" — même mise en page que doc-system avec localeSubpath vide ; les noms de dossiers de locale BCP-47 sont conservés (localePathLowercase utilise par défaut false). Voir intégration VitePress.
  • docsOutput.style = "nextra" — même mise en page que doc-system avec localeSubpath vide ; la locale source se trouve sous un dossier de locale (par exemple content/en/ lorsque l'anglais est la source). Voir intégration Nextra.

Préréglage Docusaurus (pages principales de documentation) :

text
docs/guide.md  →  i18n/de/docusaurus-plugin-content-docs/current/guide.md

Préréglage Starlight (forme de bloc identique, chemins différents) :

text
src/content/docs/guide.md  →  src/content/docs/de/guide.md

Préréglage VitePress (anglais à la racine du contenu, dossiers de locale à côté de la source) :

text
docs/guide/quick-start.md  →  docs/de/guide/quick-start.md

Préréglage Nextra (anglais sous un dossier de paramètres régionaux, dossiers de paramètres régionaux frères pour les cibles) :

text
content/en/guide/getting-started.mdx  →  content/pt-BR/guide/getting-started.mdx

Étiquettes JSON facultatives — chaînes d'interface Docusaurus provenant de docusaurusCatalogDir (pas le contenu du corps MDX) :

text
i18n/en/sidebar.json  →  i18n/de/sidebar.json

Starlight fournit des chaînes d'interface pour de nombreuses locales ; les remplacements personnalisés facultatifs utilisent src/content/i18n/en.json avec jsonPathTemplate: "{outputDir}/{locale}.json" dans un bloc docs[] séparé si nécessaire.

Les chaînes de navigation/barre latérale/pied de page de VitePress ne sont pas en markdown — configurez docsOutput.vitepressThemeCatalog et traduisez à l'intérieur de translate-docs. Voir intégration VitePress.

Le dictionnaire de thème Nextra (.ts) et les étiquettes de barre latérale _meta.ts ne sont pas en markdown — utilisez docs[].nextraDictionaryPath et la collecte automatique de _meta lorsque style: "nextra", le tout à l'intérieur de translate-docs. Voir intégration Nextra.

fumadocs ​

docsOutput.style = "fumadocs" — disposition du contenu Fumadocs via docsOutput.fumadocsParser :

  • "dot" (par défaut) — suffixe de locale dans le nom de fichier à côté des fichiers de la locale source sous outputDir (pas un dossier de locale). Ceci est distinct de la forme de chemin doc-system. La langue source est sourceLocale et peut être n'importe quelle langue.
text
content/docs/guide/getting-started.mdx  →  content/docs/guide/getting-started.pt.mdx
  • "dir" — dossiers de locale de style Nextra ; utilise le même moteur doc-system avec un localeSubpath vide.
text
content/docs/en/guide/getting-started.mdx  →  content/docs/pt-BR/guide/getting-started.mdx

Les remplacements d'interface utilisateur Fumadocs (lib/layout.shared.ts) et les étiquettes de barre latérale meta.json ne sont pas en markdown — utilisez docsOutput.fumadocsUiCatalog et la collecte automatique de meta.json lorsque style: "fumadocs", le tout à l'intérieur de translate-docs. Voir intégration Fumadocs.

Pour la réécriture d'URL de liens et de ressources au-delà des corrections de liens relatifs intégrées, consultez Réécriture de liens (docsOutput.postProcessing.regexAdjustments).

Pour les captures d'écran et les ressources raster dans les pages traduites, voir Images et captures d'écran.

Espaces réservés pathTemplate / jsonPathTemplate ​

Remplacez l'emplacement d'écriture des fichiers traduits en définissant docs[].docsOutput.pathTemplate (markdown et MDX) ou jsonPathTemplate (fichiers d'étiquettes JSON). Les deux acceptent les mêmes espaces réservés. Les chemins résolus doivent rester à l'intérieur du outputDir de ce bloc (la CLI rejette les chemins qui en sortent).

Si vous utilisez un pathTemplate personnalisé, rewriteRelativeLinks prend par défaut la valeur false sauf si vous le définissez explicitement — la réécriture des liens relatifs est conçue pour docsOutput.style = "flat" sans modèle personnalisé.

Pour les dispositions intégrées (nested, flat, doc-system sans modèle personnalisé), définissez docsOutput.localePathLowercase sur true pour écrire des segments de dossier ou de nom de fichier de locale en minuscules (par exemple pt-br au lieu de pt-BR). L'alias astro-starlight et doc-system avec localeSubpath vide définissent cette valeur par défaut sur true lors du chargement de la configuration. Les valeurs personnalisées pathTemplate / jsonPathTemplate sont inchangées — utilisez {llocale} là où vous avez besoin de segments en minuscules tout en conservant {locale} comme BCP-47.

Espace réservéRôleExemple
{outputDir}Chemin absolu résolu du outputDir de ce bloc de documentation/home/acme/repo/i18n
{locale}Code de langue cible (même forme que dans la configuration / CLI)de, pt-BR
{LOCALE}Même code langue en majusculesDE, PT-BR
{llocale}Même paramètre régional en minuscules (correspond aux dossiers de routes Astro tels que pt-br, zh-cn)de, pt-br
{relPath}Chemin du fichier source relatif à la racine du projet, en notation POSIX /docs/guide.md, README.md
{stem}Nom du fichier sans l'extensionguide pour docs/guide.md
{basename}Nom du fichier avec l'extensionguide.md
{extension}Extension incluant le point.md, .mdx
{docsRoot}Chemin absolu résolu de docsOutput.docsRoot (docs par défaut si omis)/home/acme/repo/docs
{relativeToDocsRoot}{relPath} avec le préfixe docsRoot correspondant supprimé lorsque les chaînes de chemin coïncident (POSIX) ; sinon inchangédocs/guide.md (courant) ; guide.md uniquement lorsque la suppression s'applique

Exemple

Extrait de configuration :

json
{
  "outputDir": "i18n",
  "docsOutput": {
    "pathTemplate": "{outputDir}/{locale}/{relPath}"
  }
}

Pour la langue de et la source docs/guide.md, avec un répertoire racine du projet /home/acme/repo et outputDir résolu en /home/acme/repo/i18n, le chemin développé est :

text
/home/acme/repo/i18n/de/docs/guide.md

Avec docsOutput.style = "flat" et sans pathTemplate personnalisé, un modèle courant conserve uniquement le nom de fichier via {stem} et {extension}, par exemple {outputDir}/{stem}.{locale}{extension}, ce qui donne …/guide.de.md dans le outputDir résolu.

Publié sous licence MIT.