Add Chinese translation for README and implement README translation script
- Created README.zh.md for Chinese localization of the project. - Developed a README translation script to support multiple languages using Claude Agent SDK. - Implemented CLI and programmatic usage for the translation tool. - Added examples for integrating the translation tool into build scripts and CI/CD pipelines. - Enhanced error handling and logging for translation processes. - Included support for various languages and output customization options.
This commit is contained in:
Alex Newman
@@ -0,0 +1,235 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user