Docusaurus integration
Use init -t ui-docusaurus and docsOutput.style: "docusaurus" for Docusaurus documentation sites. The preset scaffolds a docs[] block with docusaurusCatalogDir so translate-docs can translate both page markdown and Docusaurus shell JSON in one command.
See also Documents, the runnable examples/docusaurus-docs demo, and examples/nextjs-app for a combined Next.js app with nested Docusaurus docs, flat README, and SVG assets.
Quick start
ai-i18n-tools init -t ui-docusaurus -P openai
# 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 buildEnable features.translateDocs and set docs[].docusaurusCatalogDir when you translate both documentation pages and site shell strings (navbar, footer, theme strings). Run docusaurus write-translations in your Docusaurus project when you upgrade @docusaurus/* or change navbar/footer/theme labels — then re-run translate-docs or sync so shell JSON is translated into each locale folder.
Page layout
English markdown and MDX live under your Docusaurus docs/ folder (for example docs-site/docs/). Translated copies are written into each locale's plugin content tree:
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.mdConfigure one docs[] block:
{
"contentPaths": ["docs-site/docs/"],
"outputDir": "docs-site/i18n",
"docusaurusCatalogDir": "docs-site/i18n/en",
"addFrontmatter": true,
"docsOutput": {
"style": "docusaurus",
"docsRoot": "docs-site/docs"
}
}Point contentPaths at the .md / .mdx files and directories written in sourceLocale. That language can be any language. Set docsRoot to the same folder Docusaurus uses as its content root. Set outputDir to the parent of each locale folder under i18n/.
Wire Docusaurus internationalization: keep targetLocales in ai-i18n-tools.config.json aligned with the locales array in docusaurus.config.js. Each localeConfigs[locale].path must match the folder name under i18n/ (for example path: "fr" for i18n/fr/).
Enable i18n in an existing site
First-time setup uses the prompt on Add i18n to a website or docs site. The checklist below is the same work by hand.
- Add the
i18nblock indocusaurus.config.js:defaultLocale,locales, andlocaleConfigs[locale].pathwhen the URL path should differ from the locale code. - Run
docusaurus write-translationssoi18n/<defaultLocale>/exists, then pointdocusaurusCatalogDirat that folder and runsync. - Custom React in
src/pagesandsrc/componentsis not markdown. Mark user-facing copy with<Translate>ortranslate()from@docusaurus/Translatesowrite-translationscan collect it intocode.json. The message has to be a static string.write-translationswritesi18n/<locale>/code.json; withdocusaurusCatalogDirset,translate-docstranslates that JSON with the rest of the shell catalog. ai-i18n-tools does not scan those JSX trees fort().
Shell strings (write-translations)
Docusaurus navbar, footer, search placeholder, and other theme/plugin labels are not extracted from markdown. Run docusaurus write-translations in your Docusaurus project to generate JSON catalogs under the default locale folder (typically i18n/en/). Then point docs[].docusaurusCatalogDir at that folder:
{
"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"
}
}
]
}When docusaurusCatalogDir is set and features.translateDocs is enabled, translate-docs translates both:
- Documentation pages — markdown/MDX from
contentPathsintoi18n/<locale>/docusaurus-plugin-content-docs/current/ - Shell JSON — navbar, footer, and theme/plugin catalogues from
i18n/en/into sibling locale folders
Do not put Docusaurus shell JSON in json[]; use docs[].docusaurusCatalogDir with Documents instead.
Example project
examples/docusaurus-docs — English sources at docs/, committed translations under i18n/<locale>/docusaurus-plugin-content-docs/current/, plus translated shell JSON. Run pnpm start on port 3100 (build + serve) so the locale dropdown works; use pnpm dev for English-only hot reload.
For UI strings, SVG translation, and a flat README in the same repository layout, see examples/nextjs-app (nested docs-site/ on port 3040).