How to Fix Docusaurus i18n Locale Issues

In this tutorial, you'll learn about How to Fix Docusaurus i18n Locale Issues. We cover key concepts, practical examples, and best practices.

Your Docusaurus internationalized site shows only the default language — translations are not applied, the locale switcher is missing, or localized pages return 404.

The Wrong Way

// Creating translation files manually without the Docusaurus i18n CLI
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current

Manual file creation misses required JSON structure. Always use the extraction CLI.

The Right Way

Step 1: Configure i18n in docusaurus.config.js

module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr', 'de', 'zh'],
    localeConfigs: {
      en: { label: 'English' },
      fr: { label: 'Français' },
      de: { label: 'Deutsch' },
      zh: { label: '中文' },
    },
  },
};

Step 2: Extract translation files

npm run write-translations -- --locale fr

This creates i18n/fr/ with JSON translation files for navbar, footer, and sidebar labels.

Step 3: Translate content separately

# Translate docs:
# Copy docs/ to i18n/fr/docusaurus-plugin-content-docs/current/
# Translate the markdown files

# Translate theme strings:
# Edit i18n/fr/code.json — contains navbar, footer, and UI text

Step 4: Build for all locales

npm run build -- --locale fr
# Or build all locales:
npm run build

The build generates build/fr/, build/de/, etc.

French locale builds — 12 translated pages, locale switcher in navbar, /fr/ prefix URLs work.

Prevention

• Always run write-translations after changing navbar, footer, or sidebar labels.
• Keep translations in Git — use the same repository for source and translations.
• The locale management pattern is used by Doda Browser's multilingual interface — extraction keys are tracked centrally, translations are separate files.

Common Mistakes with i18n locale

1. Using foldl instead of foldl' causing stack overflow on large lists
2. Forgetting deriving (Show, Eq) on custom data types needed for debugging
3. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable

These mistakes appear frequently in real-world DOCUSAURUS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ