{"id":29726235,"url":"https://github.com/playcanvas/markdown-translator","last_synced_at":"2026-06-20T04:31:19.728Z","repository":{"id":305331720,"uuid":"993697593","full_name":"playcanvas/markdown-translator","owner":"playcanvas","description":"Use Google Gemini to translate markdown files","archived":false,"fork":false,"pushed_at":"2025-07-28T16:26:16.000Z","size":115,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-19T06:50:03.410Z","etag":null,"topics":["i18n","localization","markdown"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/playcanvas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-31T10:22:50.000Z","updated_at":"2025-08-15T12:43:41.000Z","dependencies_parsed_at":"2025-07-19T17:06:06.758Z","dependency_job_id":"f2e8c19f-3e09-401e-929b-f452a6f0bb54","html_url":"https://github.com/playcanvas/markdown-translator","commit_stats":null,"previous_names":["playcanvas/markdown-translator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/playcanvas/markdown-translator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playcanvas%2Fmarkdown-translator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playcanvas%2Fmarkdown-translator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playcanvas%2Fmarkdown-translator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playcanvas%2Fmarkdown-translator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/playcanvas","download_url":"https://codeload.github.com/playcanvas/markdown-translator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/playcanvas%2Fmarkdown-translator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34557551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["i18n","localization","markdown"],"created_at":"2025-07-24T23:21:07.593Z","updated_at":"2026-06-20T04:31:19.722Z","avatar_url":"https://github.com/playcanvas.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Markdown Translator\n\nA powerful command-line tool that uses Google Gemini AI to translate markdown and MDX files from English to any specified language while preserving formatting and structure.\n\n## Features\n\n- 🌍 **Multi-language support** - Translate to 40+ languages\n- 📝 **Markdown-aware** - Preserves all markdown formatting (headers, links, code blocks, tables, etc.)\n- 🔄 **Smart chunking** - Handles large files by splitting content intelligently\n- 🎯 **Selective translation** - Only translates text content, keeps code and URLs intact\n- 📂 **Batch processing** - Translate multiple files using glob patterns (e.g., `docs/**/*.md`)\n- 🏗️ **Structure preservation** - Maintain directory structure or flatten output as needed\n- 📊 **Progress tracking** - Real-time progress indication with spinners for single files and batches\n- 🎨 **Beautiful CLI** - Colorful, user-friendly command-line interface\n- ⚡ **Fast processing** - Optimized for speed with high-performance Gemini model\n\n## Installation\n\n### Prerequisites\n\n- Node.js 16.0.0 or higher\n- Google Gemini API key ([Get one here](https://aistudio.google.com/app/apikey))\n\n\u003e **Note**: This tool uses ES modules (ESM) and requires Node.js 16+ for full compatibility.\n\n### Install dependencies\n\n```bash\nnpm install\n```\n\n### Make CLI globally available (optional)\n\n```bash\nnpm link\n```\n\nOr run directly with Node:\n\n```bash\nnode bin/cli.js\n```\n\n## Setup\n\n### 1. Get Google Gemini API Key\n\n1. Visit [Google AI Studio](https://aistudio.google.com/app/apikey)\n2. Create a new API key\n3. Copy the generated key\n\n### 2. Set API Key\n\n**Option A: Environment Variable (Recommended)**\n\n```bash\nexport GEMINI_API_KEY=\"your-api-key-here\"\n```\n\n**Option B: Command Line Argument**\n\n```bash\nmd-translate translate -i file.md -l Spanish --key your-api-key-here\n```\n\n## Usage\n\n### Basic Translation\n\n```bash\n# Translate README.md to Spanish\nmd-translate translate -i README.md -l Spanish\n\n# Translate with custom output file\nmd-translate translate -i docs/guide.md -l French -o docs/guide_fr.md\n\n# Translate using API key argument\nmd-translate translate -i file.md -l German --key your-api-key\n```\n\n### Batch Processing\n\nThe tool supports batch processing of multiple markdown files using glob patterns:\n\n```bash\n# Translate all .md files in current directory\nmd-translate translate -i \"*.md\" -l Spanish -d ./spanish/\n\n# Translate all markdown files in docs folder and subfolders\nmd-translate translate -i \"docs/**/*.md\" -l French -d ./translations/\n\n# Batch translate with flat structure (no subdirectories)\nmd-translate translate -i \"content/**/*.md\" -l German -d ./output/ --flat\n\n# Batch translate with custom suffix\nmd-translate translate -i \"*.md\" -l Japanese -d ./translated/ --suffix \"ja\"\n```\n\n### Available Commands\n\n#### `translate` - Translate a markdown or MDX file\n\n```bash\nmd-translate translate [options]\n\nOptions:\n  -i, --input \u003cpattern\u003e    Input file path or glob pattern (required)\n                          Examples: \"file.md\", \"*.md\", \"docs/**/*.md\"\n  -l, --language \u003clang\u003e    Target language (required)\n  -o, --output \u003cfile\u003e      Output file path (for single file translation)\n  -d, --output-dir \u003cdir\u003e   Output directory (for batch translation or single file)\n  -k, --key \u003capikey\u003e       Google Gemini API key (optional)\n  --flat                   Use flat structure in output directory (default: preserve structure)\n  --suffix \u003csuffix\u003e        Custom suffix for output files (default: language name)\n```\n\n#### `languages` - List supported languages\n\n```bash\nmd-translate languages\n```\n\n#### `setup` - Show setup guide\n\n```bash\nmd-translate setup\n```\n\n#### `--help` - Show help\n\n```bash\nmd-translate --help\n```\n\n## Supported Languages\n\nThe tool supports 40+ languages including:\n\n- **European**: Spanish, French, German, Italian, Portuguese, Dutch, Russian, Polish, Swedish, Norwegian, Danish, Finnish, Greek, Ukrainian, Czech, Hungarian, Romanian, Bulgarian, Croatian, Serbian, Slovak, Slovenian, Estonian, Latvian, Lithuanian, Catalan, Basque, Welsh, Irish\n- **Asian**: Chinese, Japanese, Korean, Hindi, Thai, Vietnamese, Indonesian, Malay\n- **Middle Eastern**: Arabic, Hebrew, Turkish\n\n## Examples\n\n### Single File Translation\n\n#### Example 1: Basic Translation\n\n```bash\nmd-translate translate -i README.md -l Spanish\n```\n\n**Output**: Creates `README_spanish.md` with Spanish translation\n\n#### Example 2: Custom Output Path\n\n```bash\nmd-translate translate -i docs/api.md -l French -o docs/fr/api.md\n```\n\n**Output**: Creates `docs/fr/api.md` with French translation\n\n#### Example 3: Using API Key Argument\n\n```bash\nmd-translate translate -i guide.md -l German --key AIzaSyC...\n```\n\n#### Example 4: Large File Translation\n\nThe tool automatically handles large files by splitting them into chunks:\n\n```bash\nmd-translate translate -i large-document.md -l Japanese\n```\n\n### Batch Translation\n\n#### Example 5: Translate All Markdown Files\n\n```bash\nmd-translate translate -i \"*.md\" -l Spanish -d ./spanish/\n```\n\n**Output**: Translates all `.md` files in current directory to `./spanish/` folder\n\n#### Example 6: Recursive Translation with Structure Preservation\n\n```bash\nmd-translate translate -i \"docs/**/*.md\" -l French -d ./translations/\n```\n\n**Output**: Translates all markdown files in `docs/` and preserves directory structure in `./translations/`\n\n```\ndocs/\n├── guide.md\n├── api/\n│   └── reference.md\n└── tutorials/\n    └── getting-started.md\n\n# Becomes:\ntranslations/\n├── guide_french.md\n├── api/\n│   └── reference_french.md\n└── tutorials/\n    └── getting-started_french.md\n```\n\n#### Example 7: Flat Structure Batch Translation\n\n```bash\nmd-translate translate -i \"content/**/*.md\" -l German -d ./output/ --flat\n```\n\n**Output**: Translates all files but places them in a flat structure (no subdirectories)\n\n```\ncontent/\n├── intro.md\n├── chapters/\n│   ├── chapter1.md\n│   └── chapter2.md\n└── appendix/\n    └── notes.md\n\n# Becomes:\noutput/\n├── intro_german.md\n├── chapter1_german.md\n├── chapter2_german.md\n└── notes_german.md\n```\n\n#### Example 8: Custom Suffix\n\n```bash\nmd-translate translate -i \"*.md\" -l Japanese -d ./translated/ --suffix \"ja\"\n```\n\n**Output**: Uses \"ja\" instead of \"japanese\" as the file suffix\n\n\n\n## What Gets Translated\n\n✅ **Translated**:\n- Heading text\n- Paragraph text\n- List items\n- Table content\n- Link text\n- Image alt text\n- Quote text\n\n❌ **Preserved**:\n- Code blocks and inline code\n- URLs and file paths\n- Markdown syntax characters\n- HTML tags\n- Mathematical expressions\n- Technical terms and proper nouns (when appropriate)\n\n## Output\n\nThe tool provides detailed progress feedback for both single file and batch processing:\n\n### Single File Translation Output\n\n```\n╔═══════════════════════════════════════╗\n║        Markdown Translator            ║\n║     Powered by Google Gemini AI       ║\n╚═══════════════════════════════════════╝\n\n📋 Translation Details:\n   Input:    /path/to/README.md\n   Output:   /path/to/README_spanish.md\n   Language: Spanish\n\n⠋ Translating chunk 2/3...\n✅ Translation completed successfully!\n\n📊 Summary:\n   Original length:  2,845 characters\n   Translated length: 3,120 characters\n   Language:         Spanish\n   Output file:      /path/to/README_spanish.md\n```\n\n### Batch Translation Output\n\n```\n╔═══════════════════════════════════════╗\n║        Markdown Translator            ║\n║     Powered by Google Gemini AI       ║\n╚═══════════════════════════════════════╝\n\n📋 Batch Translation Details:\n   Pattern:  docs/**/*.md\n   Output:   /path/to/translations/\n   Language: Spanish\n   Structure: Preserved\n\n⠋ [2/5] reference.md - chunk 1/2...\n✅ All translations completed successfully!\n\n📊 Summary:\n   Files processed: 5\n   Successful: 5\n   Failed: 0\n   Output directory: /path/to/translations/\n```\n\n## Error Handling\n\nThe tool provides clear error messages for common issues:\n\n- Missing or invalid API key\n- File not found\n- Invalid file format\n- Network connectivity issues\n- API rate limiting\n\n## Development\n\n### Project Structure\n\n```\nmarkdown-translator/\n├── bin/\n│   └── cli.js           # CLI entry point\n├── src/\n│   └── translator.js    # Core translation logic\n├── package.json         # Dependencies and scripts\n└── README.md           # Documentation\n```\n\n### Architecture\n\nThis project uses **ES modules (ESM)** for modern JavaScript development:\n\n- All files use `import`/`export` syntax instead of `require`/`module.exports`\n- `package.json` includes `\"type\": \"module\"` for ESM support\n- Compatible with the latest versions of dependencies (chalk 5.x, ora 8.x)\n- Requires Node.js 16+ for full ESM compatibility\n\n### Key Dependencies\n\n- `@google/generative-ai` - Google Gemini AI SDK\n- `commander` - Command-line interface framework\n- `chalk` - Terminal styling\n- `ora` - Progress spinners\n- `fs-extra` - Enhanced file system operations\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Troubleshooting\n\n### API Key Issues\n\n- Ensure your API key is valid and active\n- Check that you have sufficient quota in your Google Cloud account\n- Verify the API key has access to the Gemini API\n\n### Large File Processing\n\n- The tool automatically chunks large files\n- Each chunk is processed with a small delay to avoid rate limiting\n- Very large files may take several minutes to process\n\n### Batch Processing\n\n- Use quotes around glob patterns to prevent shell expansion: `\"*.md\"` not `*.md`\n- The `--output-dir` option is required for batch translation\n- Large batches may take considerable time; use progress indicators to monitor\n- Failed files in a batch are reported individually without stopping the process\n\n### Network Issues\n\n- Ensure you have a stable internet connection\n- The tool will retry failed requests automatically\n- Check firewall settings if you encounter connection issues\n\n## Support\n\nIf you encounter any issues or have questions:\n\n1. Check the troubleshooting section above\n2. Run `md-translate setup` for configuration help\n3. Create an issue on the project repository\n\n---\n\n**Happy translating! 🌍✨** ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplaycanvas%2Fmarkdown-translator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplaycanvas%2Fmarkdown-translator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplaycanvas%2Fmarkdown-translator/lists"}