This tutorial will walk you through the basis of the Docusaurus i18n system.
We will add French translations to a newly initialized English Docusaurus website.
Initialize a new site with
npx @docusaurus/init@latest init website classic (like this one).
docusaurus.config.js to add the i18n support for the French language.
Use the site i18n configuration to declare the i18n locales:
Add a navbar item of type
localeDropdown so that users can select the locale they want:
Start your localized site in dev mode, using the locale of your choice:
Your site is accessible at
We haven't provided any translation, and the site is mostly untranslated.
Docusaurus provides default translations for generic theme labels, such as "Next" and "Previous" for the pagination.
Please help us complete those default translations.
Each locale is a distinct standalone single-page-application: it is not possible to start the Docusaurus sites in all locales at the same time.
The French translations will be added in
Docusaurus is modular, and each content plugin has its own subfolder.
After copying files around, restart your site with
npm run start -- --locale fr.
Hot-reload will work better when editing existing files.
Open the homepage, and use the translation APIs:
Most documentation websites are generally static and don't need advanced i18n features (plurals, genders, etc.). Use a library like react-intl for more advanced use-cases.
JSON translation files are used for everything that is not contained in a Markdown document:
- React/JSX code
- Layout navbar and footer labels
- Docs sidebar category labels
Run the write-translations command:
It will extract and initialize the JSON translation files that you need to translate.
The homepage translations are statically extracted from React source code:
Plugins and themes will also write their own JSON translation files, such as:
message attribute in the JSON files of
i18n/fr, and your site layout and homepage should now be translated.
Official Docusaurus content plugins extensively use Markdown/MDX files, and allow you to translate them.
Copy your docs Markdown files to
i18n/fr/docusaurus-plugin-content-docs/current, and translate them:
current is needed for the docs versioning feature: each docs version has its own subfolder.
Copy your blog Markdown files to
i18n/fr/docusaurus-plugin-content-blog, and translate them:
Copy your pages Markdown files to
i18n/fr/docusaurus-plugin-content-pages, and translate them:
We only copy
.mdx files, as pages React components are translated through JSON translation files already.
By default, a Markdown heading
### Hello World will have a generated id
Other documents can target it with
The translated heading becomes
### Bonjour le Monde, with id
Generated ids are not always a good fit for localized sites, as it requires you to localize all the anchor links:
For localized sites, it is recommended to use explicit heading ids.
You can choose to deploy your site under a single domain, or use multiple (sub)domains.
Run the following command:
Docusaurus will build one single-page application per locale:
website/build: for the default, English language
website/build/fr: for the French language
You can now deploy the
build folder to the static hosting solution of your choice.
Static hosting providers generally redirect
/404.html by convention, always showing an English 404 page.
Localize your 404 pages by configuring your host to redirect
This is not always possible, and depends on your host: GitHub Pages can't do this, Netlify can.
You can also build your site for a single locale:
Docusaurus will not add the
/fr/ URL prefix.
On your static hosting provider:
- create one deployment per locale
- configure the appropriate build command, using the
- configure the (sub)domain of your choice for each deployment
This strategy is not possible with Github Pages, as it is only possible to have a single deployment.
It is possible to have some locales using sub-paths, and others using subdomains.
It is also possible to deploy each locale as a separate subdomain, assemble the subdomains in a single unified domain at the CDN level:
- Deploy your site as
- Configure a CDN to serve it from