readme-translate

A CLI tool for translating README files and other Markdown documents into multiple languages.

Primary use cases:

• Translate a single README.md or other Markdown file
• Translate all .md files under a directory recursively

Supported translation backends are local AI CLIs:

• Codex CLI
• Claude Code

The current implementation is a TypeScript-based CLI that supports both single-file translation and recursive directory translation.

Current Features

• Translates a single .md file and writes -<lang> suffixed output
• Recursively finds and translates .md files under a directory
• Preserves relative directory structure for directory translation
• Excludes the output directory even when it is nested inside the input directory
• Supports --include and --exclude glob filters for directory input
• Supports --from as an optional source-language hint
• Lets you choose a backend with --engine codex|claude
• Auto-detects an available backend when --engine is omitted
• Supports --out-dir, --dry-run, and --force
• Accepts both language codes such as ja and language names such as Japanese

Requirements

• Node.js 24 or later
• codex or claude must be available locally
• Bun is not required

Usage

npx readme-translate --to ja README.md

npx readme-translate --help

npx readme-translate --to fr docs

npx readme-translate --to de --dry-run docs

npx readme-translate --to es --engine claude --out-dir translated/docs docs

npx readme-translate --from English --to Japanese README.md

npx readme-translate --to fr --include "README.md" --include "guides/*.md" --exclude "drafts/**" docs

Example Use Cases

Single file:

npx readme-translate --to ja README.md

Expected result:

• Generates README-ja.md

Directory:

npx readme-translate --to fr docs

Expected result:

• Recursively translates .md files under the target directory
• Creates a sibling output directory such as docs-fr by default
• Preserves the original relative directory structure
• Excludes the output directory itself from traversal
• Lets you narrow the translation set with --include and --exclude

Project Decisions

• The package name is readme-translate
• The package is unscoped
• The package name does not include a specific language such as ja
• The package name does not include a suffix such as cli
• The tool is centered on README localization, but also supports broader Markdown directory translation
• The design assumes support for 200+ languages and does not target any single language

Naming Intent

The focus of this tool is README localization rather than generic Markdown processing. In practice, it is also designed to handle documentation directories such as docs.