Automated translation tool for React documentation using Large Language Models (LLMs). Processes markdown files, preserves formatting, and creates pull requests with translated content.
- translate-react
Automation tool for translating React documentation repositories. Uses LLM APIs to translate markdown files while preserving code blocks, formatting, and technical terminology. Integrates with GitHub to create PRs for each translated file.
Core Workflow:
- Verifies GitHub token permissions and syncs fork with upstream
- Fetches repository tree and identifies markdown files requiring translation
- Uses language detection to determine translation necessity
- Processes files in configurable batches with LLM translation
- Creates individual branches and pull requests for each file
- Updates tracking issues with progress and links to PRs
Tip
For detailed workflow analysis including timing breakdowns and bottlenecks, see WORKFLOW.md.
- Bun v1.0.0+ (primary runtime and package manager)1
- Node.js v20+ (dependency compatibility)
- SQLite3 (state persistence, usually pre-installed)
- Git (repository operations)
- GitHub Personal Access Token with
reposcope - LLM API Key (OpenAI, OpenRouter, Azure OpenAI, or compatible)
- Fork of target React documentation repository
- Write access to fork for branch/PR creation
- Optional: tracking issue in fork for progress updates
Designed for React documentation repositories but can be adapted to any markdown-based documentation with src/ directory structure (with some tweaks).
git clone https://github.com/NivaldoFarias/translate-react.git && cd translate-reactbun installcp .env.example .envThen, Edit .env with your API keys (see Configuration section).
Important
Make sure to setup a .env.dev file with DEV_MODE_FORK_PR=true to create PRs against your fork instead of upstream. This prevents permission issues during development.
bun run devEnvironment variables are validated at runtime using Zod schemas. See src/utils/env.util.ts for complete schema definitions and validation rules.
These must be set in your .env (or .env.dev, for development) file:
| Variable | Description |
|---|---|
GITHUB_TOKEN |
GitHub Personal Access Token with repo scope |
OPENAI_API_KEY |
API key for LLM service (OpenAI, OpenRouter, Azure OpenAI) |
Important
All optional variables have defaults defined in src/utils/constants.util.ts.
GitHub Configuration
| Variable | Default | Description |
|---|---|---|
REPO_FORK_OWNER |
nivaldofarias |
Fork owner username/organization |
REPO_FORK_NAME |
pt-br.react.dev |
Fork repository name |
REPO_UPSTREAM_OWNER |
reactjs |
Upstream owner username/organization |
REPO_UPSTREAM_NAME |
pt-br.react.dev |
Upstream repository name |
GITHUB_REQUEST_TIMEOUT |
30000 |
GitHub API timeout (milliseconds) |
LLM Configuration
| Variable | Default | Description |
|---|---|---|
LLM_MODEL |
google/gemini-2.0-flash-exp:free |
Model ID for translation |
OPENAI_BASE_URL |
https://api.openrouter.com/v1 |
API endpoint |
OPENAI_PROJECT_ID |
— | Optional: OpenAI project ID for tracking |
MAX_TOKENS |
8192 |
Maximum tokens per LLM response |
HEADER_APP_URL |
https://github.com/NivaldoFarias/translate-react |
App URL for OpenRouter tracking |
HEADER_APP_TITLE |
translate-react v0.1.13 |
App title for OpenRouter tracking |
Translation Settings
| Variable | Default | Description |
|---|---|---|
TARGET_LANGUAGE |
pt-br |
Target translation language (ISO 639-1) |
SOURCE_LANGUAGE |
en |
Source language (ISO 639-1) |
BATCH_SIZE |
10 |
Files to process in parallel |
Development/Debug Settings
| Variable | Default | Description |
|---|---|---|
NODE_ENV |
development |
Runtime environment |
BUN_ENV |
development |
Bun-specific environment |
LOG_LEVEL |
info |
Logging verbosity (trace|debug|info|warn|error|fatal) |
LOG_TO_CONSOLE |
true |
Enable console logging in addition to file logs |
PROGRESS_ISSUE_NUMBER |
555 |
GitHub issue number for progress reports |
FORCE_SNAPSHOT_CLEAR |
false |
Clear snapshot cache on startup |
DEV_MODE_FORK_PR |
false |
Create PRs in fork (dev) vs upstream (production) |
Development mode with auto-reload on file changes:
bun run devDevelopment Configuration: Create .env.dev and set DEV_MODE_FORK_PR=true to create PRs against your fork instead of upstream. This prevents permission issues during testing.
bun startProduction Behavior: Creates PRs against upstream repository for official contributions.
translate-react/
├─ src/
│ ├── errors/ # Error handling system
│ ├── services/ # Core services
│ │ ├── github/ # GitHub API integration
│ │ ├── runner/ # Workflow orchestration
│ │ ├── database.service.ts # SQLite state persistence
│ │ ├── snapshot.service.ts # Snapshot management
│ │ └── translator.service.ts # LLM translation engine
│ ├── utils/ # Utilities and constants
│ └── index.ts # Entry point
│
├── docs/ # Documentation
├── logs/ # Structured error logs (JSONL)
└── snapshots.sqlite # State persistence database
- ARCHITECTURE.md - System architecture, service design, error handling patterns, and design decisions
- WORKFLOW.md - Detailed execution workflow with timing analysis, bottleneck identification, and performance data
- ERROR_HANDLING.md - Error taxonomy, recovery mechanisms, and debugging strategies
- DEBUGGING.md - Troubleshooting guides and diagnostic procedures
- PROJECT_STRUCTURE.md - Comprehensive project organization, directory structure, and navigation guide
Contributions are welcome. Follow these guidelines:
- Fork repository and create feature branch
- Install dependencies:
bun install - Create
.env.devwith development configuration:
DEV_MODE_FORK_PR=true
FORCE_SNAPSHOT_CLEAR=true
NODE_ENV=development- Run tests:
bun test
- TypeScript: All code must be properly typed
- Bun Runtime: Use Bun exclusively (not npm/yarn/pnpm)
- Error Handling: Follow established error patterns (see ERROR_HANDLING.md)
- Documentation: Maintain comprehensive JSDoc comments (see .github/instructions/jsdocs.instructions.md)
- Commits: Use conventional commit format (see .github/instructions/commit.instructions.md)
- Testing: Add tests for new features
- Code Style: Follow ESLint/Prettier configuration
- Services: Extend appropriate base classes
- Errors: Create specific error types for new failure scenarios
- Environment: Add new variables to Zod schema in
env.util.ts - Database: Use existing database service for persistence
Environment Validation Errors
Error: ❌ Invalid environment variables: - GITHUB_TOKEN: String must contain at least 1 character(s)
Solution: Ensure required variables (GITHUB_TOKEN, OPENAI_API_KEY) are set in .env file.
GitHub "Not Found" Errors
Error: GITHUB_NOT_FOUND - https://docs.github.com/rest/git/refs#get-a-reference
Solution: Set DEV_MODE_FORK_PR=true in .env.dev to create PRs against your fork instead of upstream (prevents permission issues during development).
GitHub API Rate Limiting
Error: GITHUB_RATE_LIMITED - API rate limit exceeded
Solution: Tool automatically retries with exponential backoff. For heavy usage, consider GitHub App token instead of PAT.
Translation API Errors
Error: OpenAI API error: insufficient_quota
Solution: Check API key has sufficient credits. Switch providers by changing OPENAI_BASE_URL.
SQLite Database Lock
Error: Database is locked
Solution: Ensure no other instances are running. In development, use FORCE_SNAPSHOT_CLEAR=true to reset database.
Tip
For a more detailed debugging guidance, see DEBUGGING.md.
LOG_LEVEL="debug" bun devtail -f logs/$(ls -t logs/ | head -1) | jq '.'grep "GITHUB_NOT_FOUND" logs/*.log | jq '.'cat logs/*.log | jq '.code' | sort | uniq -c- GitHub Issues - Bug reports and feature requests
- GitHub Discussions - Questions and support
- Documentation - Detailed technical documentation
MIT License - see LICENSE file for details.
Footnotes
-
This project uses Bun exclusively. Do not use npm/yarn/pnpm. ↩