Translate Docusaurus docs into another language, MDX and code untouched
Zip your docs folder, upload it, and get back the same files translated, ready to drop into i18n/<locale>/docusaurus-plugin-content-docs/current. Import lines, Tabs and other components, admonition markers, code blocks and links stay as they are; titles, sidebar labels, descriptions and the prose are translated. The first part is free without an account; up to 1,000,000 characters of text is $5, paid once.
- import and export lines and JSX component lines copied as written
- Admonition markers (:::note, :::tip) kept; the text inside is translated
- Front matter: title, description and sidebar_label translated; id, slug, sidebar_position kept
- Heading anchors such as {#install} kept so links keep working
- Same folder paths back as a .zip; images copied unchanged
Docusaurus i18n without the copy-paste
Docusaurus expects a copy of every doc in the locale folder, translated, with the same file names. Doing that by hand, or file by file in a chat assistant, is slow, and MDX makes mistakes expensive: a translated import name or a changed prop breaks the build. This tool translates only the parts readers see and copies everything else from your files.
Inline code, link targets, image paths and MDX {expressions} are replaced with markers before translation and put back afterwards, so the model never sees them. Lines that are only JSX, such as <Tabs> or <TabItem value="mac">, are skipped. Code blocks are skipped entirely, including their comments.
After downloading
- Unzip and copy the docs-<locale> folder contents into i18n/<locale>/docusaurus-plugin-content-docs/current
- Run docusaurus write-translations for theme labels and sidebar category names, which live in JSON
- Start the site with --locale <locale> and click through
- Fix any paragraph listed in the warnings file, if there is one
Not included
Sidebar category labels, navbar and footer text live in JSON files generated by write-translations; translate those with the localization file tool. Blog posts work the same way as docs: zip the blog folder and upload it as a second job, or together with docs in one .zip.
How the tool works, what it costs and how your files are handled is on the Translate Markdown Docs page; prices for every tool are on the pricing page.
Last updated
Questions and answers
Will the build still pass?
Imports, components, props, code and link targets are copied from your files, which is where MDX builds usually break. Run the build once after copying, and check the warnings file.
Are admonitions translated?
The :::note and ::: lines are kept as written; the text between them is translated.
How much can one job hold?
Up to 1,000,000 characters of text, about 300 pages, for $5. Code and front matter keys do not count.
Can I try a few files first?
Yes. The first part is translated free and shown on screen; a job of up to 40 paragraphs is free in full.