Internationalization

Doom provides built-in support for multilingual documentation, making it easy to maintain content in multiple languages with automatic translation tools.

Language Configuration

Configure supported languages in your doom.config.yml:

Multilingual
Single Language

doom.config.yml

lang: en  # Default language

This enables the multilingual mode with English as the default. Doom supports English (en) and Chinese (zh) out of the box.

doom.config.yml

lang: null  # Disable multilingual support

Use this when your documentation only needs one language.

Directory Structure

Organize content by language using subdirectories:

docs/
├── en/                      # English documentation
│   ├── index.mdx
│   ├── getting-started.md
│   └── guides/
│       ├── index.mdx
│       └── installation.md
└── zh/                      # Chinese documentation
    ├── index.mdx
    ├── getting-started.md
    └── guides/
        ├── index.mdx
        └── installation.md

Critical: Directory structures and filenames must be identical across all language directories to ensure correct routing.

✅ Correct:
docs/en/guides/installation.md
docs/zh/guides/installation.md

❌ Incorrect:
docs/en/guides/installation.md
docs/zh/guides/install.md  # Different filename!

Static Assets Organization

Store language-specific images and assets in separate directories:

docs/public/
├── en/
│   └── images/
│       ├── screenshot.png
│       └── diagram.svg
└── zh/
    └── images/
        ├── screenshot.png
        └── diagram.svg

Reference assets using language-aware paths:

<!-- In docs/en/guide.md -->

<!-- In docs/zh/guide.md -->
![Screenshot](/zh/images/screenshot.png)

Translation Strings for Components

For reusable components that need multilingual text, use the i18n.json file:

Create i18n.json

docs/i18n.json

{
  "welcome": {
    "en": "Welcome",
    "zh": "欢迎"
  },
  "getStarted": {
    "en": "Get Started",
    "zh": "开始使用"
  },
  "documentation": {
    "en": "Documentation",
    "zh": "文档"
  },
  "apiReference": {
    "en": "API Reference",
    "zh": "API 参考"
  }
}

Use in React Components

Access translations using the useI18n hook:

shared/Welcome.tsx

import { useI18n } from '@rspress/core/runtime'

export const Welcome = () => {
  const t = useI18n()
  
  return (
    <div className="welcome">
      <h1>{t('welcome')}</h1>
      <p>{t('getStarted')}</p>
    </div>
  )
}

Use in MDX Files

Access translations directly in MDX:

welcome.mdx

import { useI18n } from '@rspress/core/runtime'

# {useI18n()('welcome')}

{useI18n()('documentation')}

<button>{useI18n()('getStarted')}</button>

The useI18n hook automatically returns text for the current language based on the active route.

AI-Powered Translation

Doom includes built-in AI translation using the translate command.

Basic Usage

Single File
Multiple Files
All Files

Translate a specific file:

doom translate \
  -g "guides/installation.md" \
  -s zh \
  -t en

Use glob patterns to translate multiple files:

doom translate \
  -g "guides/**/*.md" \
  -s zh \
  -t en

Translate everything:

doom translate \
  -g "*" \
  -s zh \
  -t en

Translation Configuration

Customize the AI translation behavior:

doom.config.yml

translate:
  # System prompt (EJS template)
  systemPrompt: |
    You are a professional technical documentation engineer, skilled in writing 
    high-quality technical documentation in <%= targetLang %>. 
    Please accurately translate the following text from <%= sourceLang %> 
    to <%= targetLang %>, maintaining the style consistent with technical 
    documentation.
    
    ## Requirements
    - Maintain fluent, natural language
    - Preserve MDX formatting
    - Do not translate URLs or technical terms
    - Keep frontmatter structure intact
    <%= if (terms) { %><%- terms %><% } %>
  
  # Optional user-defined prompt
  userPrompt: |
    Follow our style guide:
    - Use "you" instead of "we"
    - Keep sentences concise
    - Maintain consistent terminology

Translation Variables

The system prompt has access to these EJS variables:

sourceLang

string

Source language name (e.g., “中文”, “English”)

targetLang

string

Target language name (e.g., “English”, “中文”)

userPrompt

string

Custom user-defined prompt from configuration

additionalPrompts

string

Document-specific prompts from frontmatter

terms

string

Auto-generated terminology guidelines

titleTranslationPrompt

string

Auto-generated title mapping guidance

Document-Specific Translation

Control translation behavior per document using frontmatter:

---
title: Advanced Configuration
description: Deep dive into configuration options
i18n:
  additionalPrompts: |
    - Translate "widget" as "部件"
    - Keep code examples in English
    - Use formal tone
---

Force Retranslation

Bypass hash checks to force retranslation:

doom translate \
  -g "guides/setup.md" \
  -s zh \
  -t en \
  --force

Doom tracks content hashes to avoid retranslating unchanged files. Use --force to override this optimization.

Language Filtering

Build or serve specific languages only:

Include Languages
Exclude Languages

Build only specific languages:

doom build --include en zh

Build all except specific languages:

doom build --exclude ru fr

Language Redirection

Control how users are redirected based on browser language:

doom build --redirect auto

auto

default

Redirect to the closest match for navigator.language

only-default-lang

Only redirect when accessing root without a language prefix

never

Never automatically redirect users

Terminology Management

Define consistent terminology across languages:

Using the Term Component

# Welcome to <Term name="product" />

The <Term name="company" textCase="capitalize" /> platform provides...

Configure Terms

Terms are typically configured in deployment overrides. See the configuration documentation for details on setting up custom terms.

Display Terminology Table

Show all defined terms:

# Terminology

<TermsTable />

Frontmatter Translation

Frontmatter fields are handled specially during translation:

---
title: Getting Started      # ← Translated
description: Quick intro    # ← Translated
author: John Doe            # ← NOT translated
weight: 1                   # ← NOT translated
category: Guide             # ← NOT translated
---

Translation Rules

title: Always translated
description: Always translated
Other fields: Preserved as-is
Structure: Maintained exactly

Best Practices

Directory structure

Keep language directories perfectly synchronized
Use identical filenames across languages
Maintain the same folder hierarchy
Store language-specific assets in separate directories

Translation workflow

Write content in your primary language (e.g., Chinese)
Create the target language directory structure
Run the translation command
Review and refine AI-generated translations
Commit both language versions together

Component localization

Extract all user-facing strings to i18n.json
Use useI18n hook consistently
Avoid hardcoded strings in components
Test components in all supported languages

Content guidelines

Write clear, translatable source content
Avoid idioms and culturally-specific references
Use consistent terminology
Keep sentences concise for easier translation
Document translation conventions in your style guide

Translation Workflow Example

Complete workflow for adding multilingual support:

Set up directory structure

mkdir -p docs/{en,zh}

Write source content

Create your documentation in the primary language:

# Write in Chinese first
echo "# 欢迎" > docs/zh/index.mdx

Configure i18n.json

Add component translations:

{
  "welcome": {
    "zh": "欢迎",
    "en": "Welcome"
  }
}

Run AI translation

doom translate -g "*" -s zh -t en

Review translations

Check generated English files in docs/en/ for accuracy.

Test both languages

doom dev
# Visit /en and /zh routes

Build for production

doom build

Troubleshooting

Routes not matching across languages

Problem: Links break when switching languages.Solution: Ensure directory structure and filenames are identical:

# Check structure
diff -r docs/en docs/zh

Translation quality issues

Problem: AI translations are inaccurate.Solution:

Refine the systemPrompt in configuration
Add document-specific additionalPrompts
Use terminology definitions
Review and manually edit translations

Component text not translating

Problem: Component strings show in wrong language.Solution:

Verify i18n.json contains all required keys
Check useI18n hook is used correctly
Ensure no hardcoded strings in components

Advanced: Automated Translation Tool

If using Doom’s automated translation tools, you don’t need to manually maintain identical directory structures—the tool handles this automatically.

The translation command automatically:

Creates target language directory structure
Maintains file organization
Preserves links and references
Tracks translation status with content hashes

Get Started

Core Concepts

Features

Guides

Internationalization

Internationalization

Language Configuration

Directory Structure

Static Assets Organization

Translation Strings for Components

Create i18n.json

Use in React Components

Use in MDX Files

AI-Powered Translation

Basic Usage

Translation Configuration

Translation Variables

Document-Specific Translation

Force Retranslation

Language Filtering

Language Redirection

Terminology Management

Using the Term Component

Configure Terms

Display Terminology Table

Frontmatter Translation

Best Practices

Translation Workflow Example

Troubleshooting

Advanced: Automated Translation Tool

Further Reading

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Guides

​Internationalization

​Language Configuration

​Directory Structure

​Static Assets Organization

​Translation Strings for Components

​Create i18n.json

​Use in React Components

​Use in MDX Files

​AI-Powered Translation

​Basic Usage

​Translation Configuration

​Translation Variables

​Document-Specific Translation

​Force Retranslation

​Language Filtering

​Language Redirection

​Terminology Management

​Using the Term Component

​Configure Terms

​Display Terminology Table

​Frontmatter Translation

​Best Practices

​Translation Workflow Example

​Troubleshooting

​Advanced: Automated Translation Tool

​Further Reading

Build docs developers (and LLMs) love

Internationalization

Language Configuration

Directory Structure

Static Assets Organization

Translation Strings for Components

Create i18n.json

Use in React Components

Use in MDX Files

AI-Powered Translation

Basic Usage

Translation Configuration

Translation Variables

Document-Specific Translation

Force Retranslation

Language Filtering

Language Redirection

Terminology Management

Using the Term Component

Configure Terms

Display Terminology Table

Frontmatter Translation

Best Practices

Translation Workflow Example

Troubleshooting

Advanced: Automated Translation Tool

Further Reading