# README Translator
Translate README.md files to multiple languages using the Claude Agent SDK. Perfect for build scripts and CI/CD pipelines.
## Installation
```bash
npm install readme-translator
# or
npm install -g readme-translator # for CLI usage
```
## Requirements
- Node.js 18+
- **Authentication** (one of the following):
- Claude Code installed and authenticated (Pro/Max subscription) - **no API key needed**
- `ANTHROPIC_API_KEY` environment variable set (for API-based usage)
- AWS Bedrock (`CLAUDE_CODE_USE_BEDROCK=1` + AWS credentials)
- Google Vertex AI (`CLAUDE_CODE_USE_VERTEX=1` + GCP credentials)
If you have Claude Code installed and logged in with your Pro/Max subscription, the SDK will automatically use that authentication.
## CLI Usage
```bash
# Basic usage
translate-readme README.md es fr de
# With options
translate-readme -v -o ./i18n --pattern docs.{lang}.md README.md es fr de ja zh
# List supported languages
translate-readme --list-languages
```
### CLI Options
| Option | Description |
|--------|-------------|
| `-o, --output <dir>` | Output directory (default: same as source) |
| `-p, --pattern <pat>` | Output filename pattern (default: `README.{lang}.md`) |
| `--no-preserve-code` | Translate code blocks too (not recommended) |
| `-m, --model <model>` | Claude model to use (default: `sonnet`) |
| `--max-budget <usd>` | Maximum budget in USD |
| `-v, --verbose` | Show detailed progress |
| `-h, --help` | Show help message |
| `--list-languages` | List all supported language codes |
## Programmatic Usage
```typescript
import { translateReadme } from "readme-translator";
const result = await translateReadme({
source: "./README.md",
languages: ["es", "fr", "de", "ja", "zh"],
verbose: true,
});
console.log(`Translated ${result.successful} files`);
console.log(`Total cost: $${result.totalCostUsd.toFixed(4)}`);
```
### API Options
```typescript
interface TranslationOptions {
/** Source README file path */
source: string;
/** Target language codes */
languages: string[];
/** Output directory (defaults to same directory as source) */
outputDir?: string;
/** Output filename pattern (use {lang} placeholder) */
pattern?: string; // default: "README.{lang}.md"
/** Preserve code blocks without translation */
preserveCode?: boolean; // default: true
/** Claude model to use */
model?: string; // default: "sonnet"
/** Maximum budget in USD */
maxBudgetUsd?: number;
/** Verbose output */
verbose?: boolean;
}
```
### Return Value
```typescript
interface TranslationJobResult {
results: TranslationResult[];
totalCostUsd: number;
successful: number;
failed: number;
}
interface TranslationResult {
language: string;
outputPath: string;
success: boolean;
error?: string;
costUsd?: number;
}
```
## Build Script Integration
### package.json
```json
{
"scripts": {
"translate": "translate-readme README.md es fr de ja zh",
"translate:all": "translate-readme -v -o ./i18n README.md es fr de it pt ja ko zh ru ar",
"prebuild": "npm run translate"
}
}
```
### GitHub Actions
Note: CI/CD environments require an API key since Claude Code won't be authenticated there.
```yaml
name: Translate README
on:
push:
branches: [main]
paths: [README.md]
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm install -g readme-translator
- name: Translate README
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
translate-readme -v -o ./i18n README.md es fr de ja zh
- name: Commit translations
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add i18n/
git diff --staged --quiet || git commit -m "chore: update README translations"
git push
```
### Programmatic Build Script
```typescript
// scripts/translate.ts
import { translateReadme } from "readme-translator";
async function main() {
const result = await translateReadme({
source: "./README.md",
languages: (process.env.TRANSLATE_LANGS || "es,fr,de").split(","),
outputDir: "./docs/i18n",
maxBudgetUsd: 5.0,
verbose: !process.env.CI,
});
if (result.failed > 0) {
console.error("Some translations failed");
process.exit(1);
}
}
main();
```
## Supported Languages
| Code | Language | Code | Language |
|------|----------|------|----------|
| `ar` | Arabic | `ko` | Korean |
| `bg` | Bulgarian | `lt` | Lithuanian |
| `cs` | Czech | `lv` | Latvian |
| `da` | Danish | `nl` | Dutch |
| `de` | German | `no` | Norwegian |
| `el` | Greek | `pl` | Polish |
| `es` | Spanish | `pt` | Portuguese |
| `et` | Estonian | `pt-br` | Brazilian Portuguese |
| `fi` | Finnish | `ro` | Romanian |
| `fr` | French | `ru` | Russian |
| `he` | Hebrew | `sk` | Slovak |
| `hi` | Hindi | `sl` | Slovenian |
| `hu` | Hungarian | `sv` | Swedish |
| `id` | Indonesian | `th` | Thai |
| `it` | Italian | `tr` | Turkish |
| `ja` | Japanese | `uk` | Ukrainian |
| | | `vi` | Vietnamese |
| | | `zh` | Chinese (Simplified) |
| | | `zh-tw` | Chinese (Traditional) |
## Best Practices
1. **Preserve Code Blocks**: Keep `preserveCode: true` (default) to avoid breaking code examples
2. **Set Budget Limits**: Use `maxBudgetUsd` to prevent runaway costs
3. **Run on Releases Only**: In CI/CD, trigger translations only on main branch or releases
4. **Review Translations**: Automated translations are good but not perfect - consider human review for critical docs
5. **Cache Results**: Don't re-translate unchanged content - check if README changed before running
## Cost Estimation
Typical costs per language (varies by README length):
- Short README (~500 words): ~$0.01-0.02
- Medium README (~2000 words): ~$0.05-0.10
- Long README (~5000 words): ~$0.15-0.25
## License
MIT
