Build a Manual with Docusaurus #5: Multilingual and Versioning

Framework Docusaurus Documentation Static Site
3 min read

In #4 we put the docs on the internet. As users grow, two needs follow. One is wanting to read them in other languages, and the other is keeping the older docs around for people still using an older version of the product. This post covers both. And this is the point where Docusaurus shines most.

This series, Build a Manual with Docusaurus, runs in six parts.

  • #1 From Install to Your First Doc
  • #2 Sidebar and Search — Structuring Your Documentation
  • #3 Writing Content — Code Blocks, Mermaid, Admonitions
  • #4 Deploy to Cloudflare Pages and Connect a Domain
  • #5 Multilingual and Versioning ← this post
  • #6 Maintenance — Search, Accessibility, and Documentation Culture

In this post we’ll cover adding a language and pinning a version as a snapshot. Both work as built-in features, without any plugin.

Adding a Language — Built-in i18n #

Multilingual starts with declaring the languages in docusaurus.config.js.

docusaurus.config.js — multilingual 
export default {
  i18n: {
    defaultLocale: 'ko',
    locales: ['ko', 'en'],
  },
};

Then extract the framework of the text to translate. This command creates the translation slots for UI strings and docs in the i18n folder.

Generate translation framework 
npm run write-translations -- --locale en

Place the English docs under i18n/en/docusaurus-plugin-content-docs/current/ with the same filenames and translate them. To preview in a specific language, run with --locale attached.

Preview in English 
npm run start -- --locale en

To add a language-select dropdown to the top menu, add a localeDropdown item to the navbar.

Versioning — Built-in versioning #

Here Docusaurus pulls ahead of the earlier tools. In the Hugo post, there was no versioning feature, so you had to split things by folder, and in the MkDocs post, you attached a separate tool called mike. Docusaurus pins the current docs as a whole snapshot with a single command.

Pin the current docs as 1.0 
npm run docusaurus docs:version 1.0

This command copies the current docs contents into versioned_docs/version-1.0 and freezes them. After that, edits to docs become the next version, and the 1.0 docs stay as they are. To add a version-select dropdown at the top, add an item to the navbar.

docusaurus.config.js — version dropdown 
navbar: {
  items: [
    { type: 'docsVersionDropdown', position: 'left' },
  ],
}

When the product climbs to 2.0, just pin a new snapshot with docs:version 2.0. Readers can pick their own version from the dropdown.

Wrapping Up #

In this post we added a language with built-in i18n and pinned a version as a snapshot with built-in versioning. Having both multilingual and versioning built in is what makes Docusaurus strong for large-scale product documentation.

The next post is the last. We’ll add search properly and lay out the operations perspective, including accessibility and the habits that keep docs alive over time, to close out the series.

X