Skip to main content

​
doom translate

Translate documentation from one language to another using Azure OpenAI. Supports intelligent term management, chunking for large files, and frontmatter handling.

​
Usage

doom translate [root] [options]

​
Arguments

​
root
string
Root directory of the documentation. Defaults to current working directory.

​
Options

​
-s, --source
string
default:"en"
Document source language. One of: en, zh, ruExample:
doom translate --source en --target zh
​
-t, --target
string
default:"zh"
Document target language. One of: en, zh, ruExample:
doom translate --target ru
​
-g, --glob
string[]
required
Glob patterns of source directories or files to translate. Supports multiple patterns.Example:
doom translate --glob "guides/**" "api/**"
​
-C, --copy
boolean
default:"false"
Copy relative assets to target directory instead of following symlinks.Example:
doom translate --glob "**" --copy
​
-f, --force
boolean
default:"false"
Force translation ignoring hash equality check and original text.Example:
doom translate --glob "**" --force
See Global Options for additional options.

​
Supported Languages

  • en - English
  • zh - Chinese (中文)
  • ru - Russian (Русский)

​
Features

​
Smart Translation

  • AI-Powered - Uses Azure OpenAI (GPT-4.1-mini by default)
  • Context-Aware - Maintains technical documentation style
  • MDX Support - Handles both Markdown and MDX files
  • Frontmatter - Translates title and description fields
  • Code Preservation - Never translates code blocks
  • Link Preservation - Keeps all URLs unchanged

​
Terminology Management

For supported language pairs (en, zh, ru), the translator:
  • Fetches terminology from remote YAML file
  • Applies consistent term translations
  • Matches terms case-insensitively
  • Only uses relevant terms found in source

​
Chunked Translation

Files larger than 60KB are automatically split into chunks:
  • Maintains context across chunks
  • Processes each chunk sequentially
  • Reassembles translated content

​
Hash-Based Caching

Translation is skipped if:
  • Target file exists
  • Target’s sourceSHA matches current source file hash
  • --force flag not used

​
Special Handling

Copy-Only Directories: These paths are copied without translation:
  • apis/advanced_apis/**
  • apis/kubernetes_apis/**
Internal Routes: Routes matching internalRoutes config are automatically excluded.

​
Environment Variables

​
AZURE_OPENAI_ENDPOINT
string
default:"https://azure-ai-api-gateway.alauda.cn"
Azure OpenAI service endpoint
​
AZURE_OPENAI_API_KEY
string
required
Azure OpenAI API key for authentication
​
AZURE_OPENAI_MODEL
string
default:"gpt-4.1-mini"
Model to use for translation
​
OPENAI_API_VERSION
string
default:"2025-04-01-preview"
Azure OpenAI API version
​
RAW_TERMS_URL
string
Custom URL to fetch translation terminologyDefault: https://gitlab-ce.alauda.cn/alauda-public/product-doc-guide/-/raw/main/terms.yaml

​
Examples

​
Basic translation

export AZURE_OPENAI_API_KEY="your-api-key"
doom translate --source en --target zh --glob "guides/**"

​
Translate entire documentation

doom translate --glob "*"
Note: Using --glob "*" enables special mode that removes unmatched target files.

​
Translate multiple directories

doom translate --glob "getting-started/**" "tutorials/**" "api/**"

​
Force re-translation

doom translate --glob "**/*.mdx" --force

​
Translate with asset copying

doom translate --glob "**" --copy

​
Translate specific file

doom translate --glob "guides/quickstart.md"

​
English to Russian

doom translate --source en --target ru --glob "**"

​
Frontmatter Handling

​
Input File (en/guide.md)

---
title: Getting Started
description: Learn how to get started with Doom
sourceSHA: abc123
i18n:
  additionalPrompts: Use friendly tone
  disableAutoTranslation: false
---

# Getting Started

Content here...

​
Output File (zh/guide.md)

---
title: 快速开始
description: 学习如何开始使用 Doom
sourceSHA: abc123
---

# 快速开始

翻译的内容...
Note:
  • i18n field is removed in target
  • sourceSHA is updated to source file hash
  • title and description are translated

​
Disabling Auto-Translation

Prevent specific files from being translated: 
---
title: Release Notes
i18n:
  disableAutoTranslation: true
---

​
Custom Translation Prompts

Add file-specific instructions: 
---
title: Marketing Guide
i18n:
  additionalPrompts: |
    Use marketing-friendly language.
    Emphasize benefits over features.
---

​
Rate Limiting

Built-in rate limiting:
  • 50 requests per minute
  • 10 concurrent requests
  • Automatic retry on rate limit errors (up to 15 retries)

​
Output

During translation: 
info  Translating en/guides/intro.md to zh/guides/intro.md
info  Content size (85KB) exceeds limit, splitting into chunks...
info  Split content into 2 chunks
info  Translating chunk 1/2...
info  Translating chunk 2/2...
info  Successfully translated 2 chunks
info  en/guides/intro.md translated to zh/guides/intro.md

​
Configuration

Customize translation in doom.config.yaml: 
translate:
  systemPrompt: |
    Custom system prompt for translation...
  userPrompt: |
    Additional requirements...

​
Troubleshooting

​
API Key Error

Ensure AZURE_OPENAI_API_KEY is set: 
export AZURE_OPENAI_API_KEY="your-key-here"

​
Rate Limit Errors

The command automatically retries. If persistent:
  • Wait a few minutes
  • Reduce concurrency (modify source code)
  • Check your API quota

​
Translation Quality Issues

  1. Add custom prompts in frontmatter
  2. Update terminology in terms.yaml
  3. Adjust systemPrompt in config
  4. Use more specific source text

​
Large Files Timeout

Files are automatically chunked at 60KB. If still timing out:
  • Split file manually
  • Increase timeout (modify source code)
  • Use a faster model

​
Missing Translations

Check:
  • File matches glob pattern
  • Not in copy-only directories
  • Not disabled via disableAutoTranslation
  • Not in internalRoutes

​
Best Practices

  1. Start Small - Test with one file before full translation
  2. Use Terms - Maintain terminology file for consistency
  3. Review Output - Always review AI translations
  4. Version Control - Commit before bulk translation
  5. Incremental Updates - Use hash-based caching for efficiency

Build docs developers (and LLMs) love

Get started for freeTalk to us