Skip to content

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 ​

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

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

text
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

Configure one docs[] block:

json
{
  "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 i18n block in docusaurus.config.js: defaultLocale, locales, and localeConfigs[locale].path when the URL path should differ from the locale code.
  • Run docusaurus write-translations so i18n/<defaultLocale>/ exists, then point docusaurusCatalogDir at that folder and run sync.
  • Custom React in src/pages and src/components is not markdown. Mark user-facing copy with <Translate> or translate() from @docusaurus/Translate so write-translations can collect it into code.json. The message has to be a static string. write-translations writes i18n/<locale>/code.json; with docusaurusCatalogDir set, translate-docs translates that JSON with the rest of the shell catalog. ai-i18n-tools does not scan those JSX trees for t().

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:

json
{
  "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 contentPaths into i18n/<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).

Released under the MIT License.