\n\n\n\n\n\n\n[](https://www.deepl.com)\n[](https://cloud.google.com/translate)\n[](https://www.deepseek.com)\n\n**A comprehensive tool for automating the translation of PO (Portable Object) files using multiple translation APIs with advanced performance optimizations.**\n\n[Features](#features) ā¢ [Installation](#installation) ā¢ [Usage](#usage) ā¢ [Documentation](#documentation) ā¢ [Performance](#performance-guide)\n\n
\n\n---\n\n## š¤ Author\n\n**Adalberto H. Vega**\n\n[](https://github.com/yourusername)\n\n## š Description\n\nThis project provides a complete suite of scripts to automate the translation of PO files commonly used in software localization, particularly for WordPress plugins and themes. It supports multiple translation APIs (DeepL, Google Cloud Translate, DeepSeek) with advanced features like batch processing, caching, parallel translation, and progress resumption.\n\n## āØ Features\n\n### šÆ Core Features\n\n| Feature | Description | Status |\n|---------|-------------|--------|\n| š **Multi-API Support** | DeepL, Google Cloud Translate, and DeepSeek | ā
|\n| š¤ **Automated Translation** | Processes only untranslated entries in PO files | ā
|\n| š·ļø **HTML/Variable Preservation** | Maintains formatting, HTML tags, and variables (`%s`, `%d`, `{0}`) | ā
|\n| š **Progress Tracking** | Real-time progress bars with tqdm | ā
|\n| š **Error Handling** | Retry logic with exponential backoff | ā
|\n| š **WordPress Integration** | Scripts for POT/PO/MO file management with WP-CLI | ā
|\n\n### ā” Performance Optimizations\n\n| Optimization | Benefit | Speedup |\n|--------------|---------|---------|\n| š¾ **Translation Caching** | Avoid re-translating identical strings | 80-95% faster |\n| š¦ **Batch Translation** | Process multiple strings in a single API call | 5-10x faster |\n| š **Parallel Processing** | Concurrent translation with configurable workers | 2-4x faster |\n| šæ **Progress Persistence** | Resume interrupted translations without losing work | Reliability |\n| š **Compiled Regex Patterns** | Optimized HTML/variable detection | 20-30% faster |\n| š§ **Memory-Efficient** | Handle files with 100,000+ entries | Scalability |\n\n## š¦ Requirements\n\n### System Requirements\n\n\n\n\n\n- Python 3.8+\n- PowerShell 5.1+ (for automation scripts)\n- Internet connection for API access\n\n### š API Keys (choose one or more)\n\n\ncd potranslate\n```\n\n### 2. Create Virtual Environment\n\n```powershell\npython -m venv .venv\n```\n\n### 3. Activate Virtual Environment\n\n```powershell\n# Windows PowerShell\n.\\.venv\\Scripts\\Activate.ps1\n\n# Windows CMD\n.venv\\Scripts\\activate.bat\n\n# Linux/Mac\nsource .venv/bin/activate\n```\n\n### 4. Install Dependencies\n\n```powershell\npip install -r requirements.txt\n```\n\n### 5. Configure Environment Variables\n\nCreate a `.env` file in the project root:\n\n```env\n# DeepL Configuration\nDEEPL_API_KEY=your-deepl-api-key-here\n\n# Google Cloud Configuration\nGOOGLE_CLOUD_PROJECT=your-project-id\nGOOGLE_APPLICATION_CREDENTIALS=path/to/service-account.json\n\n# DeepSeek Configuration\nDEEPSEEK_API_KEY=your-deepseek-api-key-here\n```\n\n**Note**: You only need to configure the API(s) you plan to use.\n\n## š» Usage\n\n### š¬ Quick Start\n\n#### Basic Translation (Sequential)\n\n```bash\n# Using DeepL\npython translate-po-multiple.py input.po output.po --api deepl --target-lang es\n\n# Using Google Translate\npython translate-po-multiple.py input.po output.po --api google --target-lang es\n\n# Using DeepSeek\npython translate-po-multiple.py input.po output.po --api deepseek --target-lang es\n```\n\n#### ā” Optimized Translation (Recommended)\n\n```bash\n# DeepL with batch processing (5-10x faster)\npython translate-po-multiple.py input.po output.po --api deepl --batch-size 20\n\n# Google with larger batches (up to 100)\npython translate-po-multiple.py input.po output.po --api google --batch-size 50\n\n# DeepSeek with parallel processing (no batch support)\npython translate-po-multiple.py input.po output.po --api deepseek --parallel 4\n```\n\n#### š Large File Translation (with resume capability)\n\n```bash\n# Start translation with progress tracking\npython translate-po-multiple.py large.po output.po --api deepl --batch-size 30 --resume\n\n# If interrupted, resume from where it left off\npython translate-po-multiple.py large.po output.po --api deepl --batch-size 30 --resume\n```\n\n### PowerShell Automation Scripts\n\n#### Direct Translation\n\n```powershell\n# Translate a PO file using the virtual environment wrapper\n.\\trans-po.ps1 -filename \"path\\to\\file.po\"\n```\n\n#### Download Folder Workflow\n\n```powershell\n# Process file from Downloads (for WordPress plugin translations)\n.\\process-po.ps1 -FilePrefix \"elementor-1142\"\n\n# Expects: elementor-1142-es.po in Downloads\n# Outputs: elementor-1142-es_ES.po back to Downloads\n```\n\n### WordPress Translation Workflow\n\n#### 1. Generate POT and PO Files\n\n```powershell\n# Create PO file for Spanish\n.\\make-po.ps1 es\n\n# Creates: languages/your-plugin-es_ES.po\n```\n\n#### 2. Translate the PO File\n\n```powershell\n# Translate using optimized batch processing\n.\\trans-po.ps1 -filename \"languages\\your-plugin-es_ES.po\"\n```\n\n#### 3. Compile to MO File\n\n```powershell\n# Compile for WordPress\n.\\make-mo.ps1 es\n\n# Creates: languages/your-plugin-es_ES.mo\n```\n\n### Advanced Options\n\n#### Command-Line Parameters\n\n```powershell\npython translate-po-multiple.py input.po output.po [OPTIONS]\n\nOptions:\n --api {deepl,deepseek,google} Translation API (default: deepl)\n --target-lang LANG Target language code (default: es)\n --batch-size SIZE Strings per batch (default: 10)\n --parallel WORKERS Parallel workers (default: 1)\n --no-cache Disable translation caching\n --resume Resume from previous progress\n --delay SECONDS Delay between translations (default: 0.5)\n```\n\n#### Example Configurations\n\n**Small Files (< 500 entries)**\n\n```powershell\npython translate-po-multiple.py input.po output.po --api deepl\n```\n\n**Medium Files (500-5000 entries)**\n\n```powershell\n# DeepL\npython translate-po-multiple.py input.po output.po --api deepl --batch-size 20\n\n# Google\npython translate-po-multiple.py input.po output.po --api google --batch-size 50\n```\n\n**Large Files (5000+ entries)**\n\n```powershell\n# DeepL with resume capability\npython translate-po-multiple.py input.po output.po \\\n --api deepl \\\n --batch-size 30 \\\n --resume\n\n# Google with maximum batch size\npython translate-po-multiple.py input.po output.po \\\n --api google \\\n --batch-size 100 \\\n --resume\n```\n\n**DeepSeek (no batch support)**\n\n```powershell\npython translate-po-multiple.py input.po output.po \\\n --api deepseek \\\n --parallel 3 \\\n --delay 0.3\n```\n\n**Development/Testing**\n\n```powershell\n# Force fresh translations without cache\npython translate-po-multiple.py test.po output.po \\\n --api deepl \\\n --no-cache \\\n --batch-size 5\n```\n\n## š Performance Guide\n\n### š Expected Performance Improvements\n\n| File Size | Method | Time (Before) | Time (After) | Improvement |\n|-----------|--------|---------------|--------------|-------------|\n| 500 entries | Sequential | ā±ļø ~4 min | ā” ~45 sec |  |\n| 1000 entries | Batch (20) | ā±ļø ~8 min | ā” ~90 sec |  |\n| 5000 entries | Batch (50) | ā±ļø ~42 min | ā” ~5 min |  |\n| 10000 entries | Batch + Cache | ā±ļø ~84 min | ā” ~6 min |  |\n\n### š” Optimization Recommendations\n\n\n\n| ā
| \nAlways use caching unless testing (enabled by default) | \n
\n\n| š¦ | \nUse batch translation for DeepL and Google (10-50x faster) | \n
\n\n| š | \nUse parallel processing for DeepSeek (2-4x faster) | \n
\n\n| š¾ | \nEnable resume for files > 1000 entries | \n
\n\n| ā²ļø | \nAdjust delay if hitting rate limits | \n
\n
\n\n### š¾ Caching Benefits\n\n```mermaid\ngraph LR\n A[First run] -->|Normal speed| B[Cache built]\n B -->|50% new| C[~2x faster]\n B -->|100% cached| D[~50x faster ā”]\n style D fill:#90EE90\n```\n\n- š **First run**: Normal speed, builds cache\n- ā” **Second run (50% new content)**: ~2x faster\n- š **Re-translation (100% cached)**: ~50x faster (instant)\n\n## File Structure\n\n```\npotranslate/\nāāā translate-po.py # Original DeepL-only translator\nāāā translate-po-multiple.py # Multi-API translator with optimizations\nāāā trans-po.ps1 # Virtual environment wrapper\nāāā process-po.ps1 # Downloads folder workflow\nāāā make-po.ps1 # Generate POT/PO files (WP-CLI)\nāāā make-mo.ps1 # Compile MO files (WP-CLI)\nāāā requirements.txt # Python dependencies\nāāā .env # API keys (not committed)\nāāā .gitignore # Git ignore rules\nāāā README.md # This file\nāāā CLAUDE.md # Project instructions for Claude Code\nāāā OPTIMIZATION_GUIDE.md # Detailed optimization guide\nāāā SECURITY.md # Security best practices\nāāā CRUSH.md # Code style guide\nāāā .translation_cache/ # Translation cache (auto-created)\n```\n\n## Output File Formats\n\n### Standard Translation\n\n- **Input**: `filename-es.po`\n- **Output**: `filename-es_ES.po`\n\n### WordPress Translation\n\n- **POT**: `plugin-name.pot` (translation template)\n- **PO**: `plugin-name-es_ES.po` (Spanish translations)\n- **MO**: `plugin-name-es_ES.mo` (compiled binary)\n\n## š Troubleshooting\n\n### ā ļø Common Issues\n\n\nš« Rate Limiting Errors (429)
\n\n**Symptoms**: API returns \"Too Many Requests\"\n\n**Solutions**:\n\n```bash\n# Increase delay between requests\n--delay 1.0\n\n# Reduce batch size\n--batch-size 10\n\n# Reduce parallel workers\n--parallel 2\n```\n\n \n\n\nš¾ Out of Memory
\n\n**Symptoms**: Process crashes with memory errors\n\n**Solutions**:\n\n```bash\n# Reduce batch size\n--batch-size 5\n\n# Enable resume for smaller sessions\n--resume\n```\n\n \n\n\nš Cache Not Working
\n\n**Symptoms**: Translations seem slow on repeat runs\n\n**Solutions**:\n\n1. ā
Check if `.translation_cache/` directory exists\n2. ā
Verify `.pkl` files are being created\n3. ā
Ensure not using `--no-cache` flag\n4. ā
Check file permissions\n\n \n\n\nš Progress File Corruption
\n\n**Symptoms**: Resume fails or restarts from beginning\n\n**Solutions**:\n\n```bash\n# Delete progress file and restart\nrm output.po.progress\npython translate-po-multiple.py input.po output.po --resume\n```\n\n \n\n\nš API Authentication Errors
\n\n**DeepL**:\n\n- ā
Verify `DEEPL_API_KEY` in `.env`\n- ā
Check API key validity at DeepL dashboard\n\n**Google**:\n\n- ā
Verify `GOOGLE_CLOUD_PROJECT` and `GOOGLE_APPLICATION_CREDENTIALS`\n- ā
Ensure service account has Translation API permissions\n- ā
Check JSON key file path is correct\n\n**DeepSeek**:\n\n- ā
Verify `DEEPSEEK_API_KEY` in `.env`\n- ā
Check account has sufficient credits\n\n \n\n### Debugging\n\nEnable debug logging:\n\n```powershell\n# Set logging level to DEBUG in script\n# Or use Python logging configuration\npython -u translate-po-multiple.py input.po output.po --api deepl\n```\n\nView cache contents:\n\n```powershell\n# Check cache directory\nls .translation_cache/\n\n# Count cached translations\n(ls .translation_cache/*.pkl).Count\n```\n\nMonitor progress file:\n\n```powershell\n# Watch progress in real-time\nGet-Content output.po.progress -Wait\n```\n\n## š API Comparison\n\n| Feature |  |  |  |\n|---------|-------|--------|----------|\n| šÆ **Quality** | āāāāā Excellent | āāāā Very Good | āāā Good |\n| š¦ **Batch Support** | ā
Yes (50+) | ā
Yes (100) | ā No |\n| ā±ļø **Rate Limits** | š” Moderate | š¢ High | š” Moderate |\n| š **Cost (Free)** | 500K chars/mo | $10 credit | Limited |\n| š° **Cost (Paid)** | ā¬5.49/mo+ | Pay-per-char | Very low |\n| š·ļø **HTML Preservation** | ā
Native | āļø Manual | āļø Manual |\n| šÆ **Best For** | Quality | Volume | Budget |\n\n## š Best Practices\n\n### š Security\n\n\n| š | Never commit .env file or API keys |
\n| š¤ | Use service account with minimal permissions (Google) |
\n| š | Rotate API keys periodically |
\n| š | Review SECURITY.md for detailed guidelines |
\n
\n\n### ā” Performance\n\n\n| š¦ | Start with batch translation for DeepL/Google |
\n| š | Use parallel processing for DeepSeek |
\n| š¾ | Enable caching for repeat translations |
\n| š | Use --resume for large files |
\n
\n\n### š§ Workflow\n\n1. ā
Always test with small sample first\n2. š Use version control for PO files\n3. šļø Review automated translations\n4. š¾ Keep backup of original files\n\n### š° Cost Optimization\n\n```\nāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā\nā š¾ Cache ā 95% fewer API calls ā\nā š¦ Batch ā 90% cost reduction ā\nā š® DeepSeek ā Budget-friendly option ā\nā š Monitor ā Track usage dashboards ā\nāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā\n```\n\n## š Documentation\n\n| Document | Description |\n|----------|-------------|\n| š **README.md** | General usage and setup (this file) |\n| ā” **OPTIMIZATION_GUIDE.md** | Detailed performance optimization guide |\n| š¤ **CLAUDE.md** | Project instructions and architecture |\n| š **SECURITY.md** | Security best practices |\n| š **CRUSH.md** | Code style and development guidelines |\n\n## š¤ Contributing\n\nContributions are welcome! Please:\n\n1. š“ Fork the repository\n2. šæ Create a feature branch\n3. š Follow code style in `CRUSH.md`\n4. ā
Add tests if applicable\n5. š Submit a pull request\n\n[](CONTRIBUTING.md)\n\n## š¬ Support\n\nFor issues, questions, or suggestions:\n\n[](https://github.com/yourusername/potranslate/issues)\n[](https://github.com/yourusername/potranslate/discussions)\n[](https://github.com/yourusername/potranslate/wiki)\n\n## š Changelog\n\n### Version 2.0 (Latest) \n\n\n| āØ | Added multi-API support (DeepL, Google, DeepSeek) |
\n| š¾ | Implemented translation caching (80-95% faster) |
\n| š¦ | Added batch translation support (5-10x faster) |
\n| š | Implemented parallel processing (2-4x faster) |
\n| šæ | Added progress persistence and resume capability |
\n| š | Optimized regex patterns (20-30% faster) |
\n| š§ | Memory-efficient processing for large files |
\n| š | Created comprehensive optimization guide |
\n| š§ | Added command-line options for all features |
\n
\n\n### Version 1.0\n\n\n| š | Initial release with DeepL support |
\n| š | Basic PO file translation |
\n| āļø | PowerShell automation scripts |
\n| š | WordPress WP-CLI integration |
\n
\n\n## š License\n\n[](https://opensource.org/licenses/MIT)\n\n```\nMIT License\n\nCopyright (c) 2024 Adalberto H. Vega\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n## š Acknowledgments\n\n\n\n| Technology | Purpose |\n|------------|---------|\n|  | High-quality translation API |\n|  | Scalable translation infrastructure |\n|  | Cost-effective AI translation |\n|  | Excellent PO file handling library |\n|  | Beautiful progress bars |\n\n
\n\n---\n\n\n\n### š **Happy Translating!** āØ\n\n[](https://github.com/yourusername)\n[](https://python.org)\n[](https://github.com)\n\nā **Star this repo if you find it helpful!** ā\n\n
\n"}, "761020141e357b911fc79a70b5a8de7e0e0cf1b9": {"t": 1785772116.7478926, "n": 21992, "h": "121d47305f028f3e", "c": "# PO File Translator\n\n\n\n\n\n\n\n\n[](https://www.deepl.com)\n[](https://cloud.google.com/translate)\n[](https://www.deepseek.com)\n\n**A comprehensive tool for automating the translation of PO (Portable Object) files using multiple translation APIs with advanced performance optimizations.**\n\n[Features](#features) ā¢ [Installation](#installation) ā¢ [Usage](#usage) ā¢ [Documentation](#documentation) ā¢ [Performance](#performance-guide)\n\n
\n\n---\n\n## š¤ Author\n\n**Adalberto H. Vega**\n\n[](https://github.com/yourusername)\n\n## š Description\n\nThis project provides a complete suite of scripts to automate the translation of PO files commonly used in software localization, particularly for WordPress plugins and themes. It supports multiple translation APIs (DeepL, Google Cloud Translate, DeepSeek) with advanced features like batch processing, caching, parallel translation, and progress resumption.\n\n## āØ Features\n\n### šÆ Core Features\n\n| Feature | Description | Status |\n|---------|-------------|--------|\n| š **Multi-API Support** | DeepL, Google Cloud Translate, and DeepSeek | ā
|\n| š¤ **Automated Translation** | Processes only untranslated entries in PO files | ā
|\n| š·ļø **HTML/Variable Preservation** | Maintains formatting, HTML tags, and variables (`%s`, `%d`, `{0}`) | ā
|\n| š **Progress Tracking** | Real-time progress bars with tqdm | ā
|\n| š **Error Handling** | Retry logic with exponential backoff | ā
|\n| š **WordPress Integration** | Scripts for POT/PO/MO file management with WP-CLI | ā
|\n\n### ā” Performance Optimizations\n\n| Optimization | Benefit | Speedup |\n|--------------|---------|---------|\n| š¾ **Translation Caching** | Avoid re-translating identical strings | 80-95% faster |\n| š¦ **Batch Translation** | Process multiple strings in a single API call | 5-10x faster |\n| š **Parallel Processing** | Concurrent translation with configurable workers | 2-4x faster |\n| šæ **Progress Persistence** | Resume interrupted translations without losing work | Reliability |\n| š **Compiled Regex Patterns** | Optimized HTML/variable detection | 20-30% faster |\n| š§ **Memory-Efficient** | Handle files with 100,000+ entries | Scalability |\n\n## š¦ Requirements\n\n### System Requirements\n\n\n\n\n\n- Python 3.8+\n- PowerShell 5.1+ (for automation scripts)\n- Internet connection for API access\n\n### š API Keys (choose one or more)\n\n\n\n\n![\"DeepL\"/](\"https://img.shields.io/badge/DeepL-0F2B46?style=flat&logo=deepl&logoColor=white\")
\nDeepL API Key
\nRecommended for quality\n | \n\n![\"Google](\"https://img.shields.io/badge/Google_Cloud-4285F4?style=flat&logo=google-cloud&logoColor=white\")
\nGoogle Cloud Project
\nTranslation API enabled\n | \n\n![\"DeepSeek\"/](\"https://img.shields.io/badge/DeepSeek-412991?style=flat&logo=openai&logoColor=white\")
\nDeepSeek API Key
\nCost-effective alternative\n | \n
\n
\n\n### š Python Dependencies\n\n\n\n\n\n\n```python\npolib>=1.2.0 # PO file parsing\ndeepl>=1.16.1 # DeepL API client\npython-dotenv>=1.0.0 # Environment variables\ntqdm>=4.66.1 # Progress bars\nrequests # HTTP requests\nopenai # DeepSeek API client\ngoogle-cloud-translate # Google Cloud Translate v3\n```\n\n## š§ API Setup\n\n\nšµ DeepL API Key
\n\n1. **Create an Account**: Sign up at [DeepL.com](https://www.deepl.com)\n2. **Access API Keys**: Navigate to your account's 'API Keys' section\n3. **Create New Key**: Generate a new API key\n4. **Choose Plan**:\n - š **Free Plan**: 500,000 characters/month\n - š **Pro Plan**: Unlimited translations with higher rate limits\n5. **Security**: Keep your API key confidential\n\nš For more details: [DeepL API Documentation](https://developers.deepl.com/docs/getting-started/auth)\n\n \n\n\nš“ Google Cloud Translate
\n\n1. **Create Project**: Go to [Google Cloud Console](https://console.cloud.google.com)\n2. **Enable API**: Enable the Cloud Translation API\n3. **Create Service Account**:\n - Go to IAM & Admin ā Service Accounts\n - Create a new service account\n - Grant \"Cloud Translation API User\" role\n4. **Generate Key**: Download JSON key file\n5. **Save Key**: Store JSON file in project directory (gitignored)\n\n \n\n\nš£ DeepSeek API Key
\n\n1. **Sign Up**: Create account at [DeepSeek Platform](https://platform.deepseek.com)\n2. **Generate Key**: Navigate to API Keys section\n3. **Cost-Effective**: Lower pricing than DeepL/Google for high volumes\n\n \n\n---\n\n## š Installation\n\n### 1. Clone the Repository\n```powershell\ngit clone \ncd potranslate\n```\n\n### 2. Create Virtual Environment\n```powershell\npython -m venv .venv\n```\n\n### 3. Activate Virtual Environment\n```powershell\n# Windows PowerShell\n.\\.venv\\Scripts\\Activate.ps1\n\n# Windows CMD\n.venv\\Scripts\\activate.bat\n\n# Linux/Mac\nsource .venv/bin/activate\n```\n\n### 4. Install Dependencies\n```powershell\npip install -r requirements.txt\n```\n\n### 5. Configure Environment Variables\n\nCreate a `.env` file in the project root:\n\n```env\n# DeepL Configuration\nDEEPL_API_KEY=your-deepl-api-key-here\n\n# Google Cloud Configuration\nGOOGLE_CLOUD_PROJECT=your-project-id\nGOOGLE_APPLICATION_CREDENTIALS=path/to/service-account.json\n\n# DeepSeek Configuration\nDEEPSEEK_API_KEY=your-deepseek-api-key-here\n```\n\n**Note**: You only need to configure the API(s) you plan to use.\n\n## š» Usage\n\n### š¬ Quick Start\n\n#### Basic Translation (Sequential)\n\n```bash\n# Using DeepL\npython translate-po-multiple.py input.po output.po --api deepl --target-lang es\n\n# Using Google Translate\npython translate-po-multiple.py input.po output.po --api google --target-lang es\n\n# Using DeepSeek\npython translate-po-multiple.py input.po output.po --api deepseek --target-lang es\n```\n\n#### ā” Optimized Translation (Recommended)\n\n```bash\n# DeepL with batch processing (5-10x faster)\npython translate-po-multiple.py input.po output.po --api deepl --batch-size 20\n\n# Google with larger batches (up to 100)\npython translate-po-multiple.py input.po output.po --api google --batch-size 50\n\n# DeepSeek with parallel processing (no batch support)\npython translate-po-multiple.py input.po output.po --api deepseek --parallel 4\n```\n\n#### š Large File Translation (with resume capability)\n\n```bash\n# Start translation with progress tracking\npython translate-po-multiple.py large.po output.po --api deepl --batch-size 30 --resume\n\n# If interrupted, resume from where it left off\npython translate-po-multiple.py large.po output.po --api deepl --batch-size 30 --resume\n```\n\n### PowerShell Automation Scripts\n\n#### Direct Translation\n```powershell\n# Translate a PO file using the virtual environment wrapper\n.\\trans-po.ps1 -filename \"path\\to\\file.po\"\n```\n\n#### Download Folder Workflow\n```powershell\n# Process file from Downloads (for WordPress plugin translations)\n.\\process-po.ps1 -FilePrefix \"elementor-1142\"\n\n# Expects: elementor-1142-es.po in Downloads\n# Outputs: elementor-1142-es_ES.po back to Downloads\n```\n\n### WordPress Translation Workflow\n\n#### 1. Generate POT and PO Files\n```powershell\n# Create PO file for Spanish\n.\\make-po.ps1 es\n\n# Creates: languages/your-plugin-es_ES.po\n```\n\n#### 2. Translate the PO File\n```powershell\n# Translate using optimized batch processing\n.\\trans-po.ps1 -filename \"languages\\your-plugin-es_ES.po\"\n```\n\n#### 3. Compile to MO File\n```powershell\n# Compile for WordPress\n.\\make-mo.ps1 es\n\n# Creates: languages/your-plugin-es_ES.mo\n```\n\n### Advanced Options\n\n#### Command-Line Parameters\n\n```powershell\npython translate-po-multiple.py input.po output.po [OPTIONS]\n\nOptions:\n --api {deepl,deepseek,google} Translation API (default: deepl)\n --target-lang LANG Target language code (default: es)\n --batch-size SIZE Strings per batch (default: 10)\n --parallel WORKERS Parallel workers (default: 1)\n --no-cache Disable translation caching\n --resume Resume from previous progress\n --delay SECONDS Delay between translations (default: 0.5)\n```\n\n#### Example Configurations\n\n**Small Files (< 500 entries)**\n```powershell\npython translate-po-multiple.py input.po output.po --api deepl\n```\n\n**Medium Files (500-5000 entries)**\n```powershell\n# DeepL\npython translate-po-multiple.py input.po output.po --api deepl --batch-size 20\n\n# Google\npython translate-po-multiple.py input.po output.po --api google --batch-size 50\n```\n\n**Large Files (5000+ entries)**\n```powershell\n# DeepL with resume capability\npython translate-po-multiple.py input.po output.po \\\n --api deepl \\\n --batch-size 30 \\\n --resume\n\n# Google with maximum batch size\npython translate-po-multiple.py input.po output.po \\\n --api google \\\n --batch-size 100 \\\n --resume\n```\n\n**DeepSeek (no batch support)**\n```powershell\npython translate-po-multiple.py input.po output.po \\\n --api deepseek \\\n --parallel 3 \\\n --delay 0.3\n```\n\n**Development/Testing**\n```powershell\n# Force fresh translations without cache\npython translate-po-multiple.py test.po output.po \\\n --api deepl \\\n --no-cache \\\n --batch-size 5\n```\n\n## š Performance Guide\n\n### š Expected Performance Improvements\n\n| File Size | Method | Time (Before) | Time (After) | Improvement |\n|-----------|--------|---------------|--------------|-------------|\n| 500 entries | Sequential | ā±ļø ~4 min | ā” ~45 sec |  |\n| 1000 entries | Batch (20) | ā±ļø ~8 min | ā” ~90 sec |  |\n| 5000 entries | Batch (50) | ā±ļø ~42 min | ā” ~5 min |  |\n| 10000 entries | Batch + Cache | ā±ļø ~84 min | ā” ~6 min |  |\n\n### š” Optimization Recommendations\n\n\n\n| ā
| \nAlways use caching unless testing (enabled by default) | \n
\n\n| š¦ | \nUse batch translation for DeepL and Google (10-50x faster) | \n
\n\n| š | \nUse parallel processing for DeepSeek (2-4x faster) | \n
\n\n| š¾ | \nEnable resume for files > 1000 entries | \n
\n\n| ā²ļø | \nAdjust delay if hitting rate limits | \n
\n
\n\n### š¾ Caching Benefits\n\n```mermaid\ngraph LR\n A[First run] -->|Normal speed| B[Cache built]\n B -->|50% new| C[~2x faster]\n B -->|100% cached| D[~50x faster ā”]\n style D fill:#90EE90\n```\n\n- š **First run**: Normal speed, builds cache\n- ā” **Second run (50% new content)**: ~2x faster\n- š **Re-translation (100% cached)**: ~50x faster (instant)\n\n## File Structure\n\n```\npotranslate/\nāāā translate-po.py # Original DeepL-only translator\nāāā translate-po-multiple.py # Multi-API translator with optimizations\nāāā trans-po.ps1 # Virtual environment wrapper\nāāā process-po.ps1 # Downloads folder workflow\nāāā make-po.ps1 # Generate POT/PO files (WP-CLI)\nāāā make-mo.ps1 # Compile MO files (WP-CLI)\nāāā requirements.txt # Python dependencies\nāāā .env # API keys (not committed)\nāāā .gitignore # Git ignore rules\nāāā README.md # This file\nāāā CLAUDE.md # Project instructions for Claude Code\nāāā OPTIMIZATION_GUIDE.md # Detailed optimization guide\nāāā SECURITY.md # Security best practices\nāāā CRUSH.md # Code style guide\nāāā .translation_cache/ # Translation cache (auto-created)\n```\n\n## Output File Formats\n\n### Standard Translation\n- **Input**: `filename-es.po`\n- **Output**: `filename-es_ES.po`\n\n### WordPress Translation\n- **POT**: `plugin-name.pot` (translation template)\n- **PO**: `plugin-name-es_ES.po` (Spanish translations)\n- **MO**: `plugin-name-es_ES.mo` (compiled binary)\n\n## š Troubleshooting\n\n### ā ļø Common Issues\n\n\nš« Rate Limiting Errors (429)
\n\n**Symptoms**: API returns \"Too Many Requests\"\n\n**Solutions**:\n```bash\n# Increase delay between requests\n--delay 1.0\n\n# Reduce batch size\n--batch-size 10\n\n# Reduce parallel workers\n--parallel 2\n```\n\n \n\n\nš¾ Out of Memory
\n\n**Symptoms**: Process crashes with memory errors\n\n**Solutions**:\n```bash\n# Reduce batch size\n--batch-size 5\n\n# Enable resume for smaller sessions\n--resume\n```\n\n \n\n\nš Cache Not Working
\n\n**Symptoms**: Translations seem slow on repeat runs\n\n**Solutions**:\n1. ā
Check if `.translation_cache/` directory exists\n2. ā
Verify `.pkl` files are being created\n3. ā
Ensure not using `--no-cache` flag\n4. ā
Check file permissions\n\n \n\n\nš Progress File Corruption
\n\n**Symptoms**: Resume fails or restarts from beginning\n\n**Solutions**:\n```bash\n# Delete progress file and restart\nrm output.po.progress\npython translate-po-multiple.py input.po output.po --resume\n```\n\n \n\n\nš API Authentication Errors
\n\n**DeepL**:\n- ā
Verify `DEEPL_API_KEY` in `.env`\n- ā
Check API key validity at DeepL dashboard\n\n**Google**:\n- ā
Verify `GOOGLE_CLOUD_PROJECT` and `GOOGLE_APPLICATION_CREDENTIALS`\n- ā
Ensure service account has Translation API permissions\n- ā
Check JSON key file path is correct\n\n**DeepSeek**:\n- ā
Verify `DEEPSEEK_API_KEY` in `.env`\n- ā
Check account has sufficient credits\n\n \n\n### Debugging\n\nEnable debug logging:\n```powershell\n# Set logging level to DEBUG in script\n# Or use Python logging configuration\npython -u translate-po-multiple.py input.po output.po --api deepl\n```\n\nView cache contents:\n```powershell\n# Check cache directory\nls .translation_cache/\n\n# Count cached translations\n(ls .translation_cache/*.pkl).Count\n```\n\nMonitor progress file:\n```powershell\n# Watch progress in real-time\nGet-Content output.po.progress -Wait\n```\n\n## š API Comparison\n\n| Feature |  |  |  |\n|---------|-------|--------|----------|\n| šÆ **Quality** | āāāāā Excellent | āāāā Very Good | āāā Good |\n| š¦ **Batch Support** | ā
Yes (50+) | ā
Yes (100) | ā No |\n| ā±ļø **Rate Limits** | š” Moderate | š¢ High | š” Moderate |\n| š **Cost (Free)** | 500K chars/mo | $10 credit | Limited |\n| š° **Cost (Paid)** | ā¬5.49/mo+ | Pay-per-char | Very low |\n| š·ļø **HTML Preservation** | ā
Native | āļø Manual | āļø Manual |\n| šÆ **Best For** | Quality | Volume | Budget |\n\n## š Best Practices\n\n### š Security\n\n\n| š | Never commit .env file or API keys |
\n| š¤ | Use service account with minimal permissions (Google) |
\n| š | Rotate API keys periodically |
\n| š | Review SECURITY.md for detailed guidelines |
\n
\n\n### ā” Performance\n\n\n| š¦ | Start with batch translation for DeepL/Google |
\n| š | Use parallel processing for DeepSeek |
\n| š¾ | Enable caching for repeat translations |
\n| š | Use --resume for large files |
\n
\n\n### š§ Workflow\n\n1. ā
Always test with small sample first\n2. š Use version control for PO files\n3. šļø Review automated translations\n4. š¾ Keep backup of original files\n\n### š° Cost Optimization\n\n```\nāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā\nā š¾ Cache ā 95% fewer API calls ā\nā š¦ Batch ā 90% cost reduction ā\nā š® DeepSeek ā Budget-friendly option ā\nā š Monitor ā Track usage dashboards ā\nāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā\n```\n\n## š Documentation\n\n| Document | Description |\n|----------|-------------|\n| š **README.md** | General usage and setup (this file) |\n| ā” **OPTIMIZATION_GUIDE.md** | Detailed performance optimization guide |\n| š¤ **CLAUDE.md** | Project instructions and architecture |\n| š **SECURITY.md** | Security best practices |\n| š **CRUSH.md** | Code style and development guidelines |\n\n## š¤ Contributing\n\nContributions are welcome! Please:\n\n1. š“ Fork the repository\n2. šæ Create a feature branch\n3. š Follow code style in `CRUSH.md`\n4. ā
Add tests if applicable\n5. š Submit a pull request\n\n[](CONTRIBUTING.md)\n\n## š¬ Support\n\nFor issues, questions, or suggestions:\n\n[](https://github.com/yourusername/potranslate/issues)\n[](https://github.com/yourusername/potranslate/discussions)\n[](https://github.com/yourusername/potranslate/wiki)\n\n## š Changelog\n\n### Version 2.0 (Latest) \n\n\n| āØ | Added multi-API support (DeepL, Google, DeepSeek) |
\n| š¾ | Implemented translation caching (80-95% faster) |
\n| š¦ | Added batch translation support (5-10x faster) |
\n| š | Implemented parallel processing (2-4x faster) |
\n| šæ | Added progress persistence and resume capability |
\n| š | Optimized regex patterns (20-30% faster) |
\n| š§ | Memory-efficient processing for large files |
\n| š | Created comprehensive optimization guide |
\n| š§ | Added command-line options for all features |
\n
\n\n### Version 1.0\n\n\n| š | Initial release with DeepL support |
\n| š | Basic PO file translation |
\n| āļø | PowerShell automation scripts |
\n| š | WordPress WP-CLI integration |
\n
\n\n## š License\n\n[](https://opensource.org/licenses/MIT)\n\n```\nMIT License\n\nCopyright (c) 2024 Adalberto H. Vega\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n## š Acknowledgments\n\n\n\n| Technology | Purpose |\n|------------|---------|\n|  | High-quality translation API |\n|  | Scalable translation infrastructure |\n|  | Cost-effective AI translation |\n|  | Excellent PO file handling library |\n|  | Beautiful progress bars |\n\n
\n\n---\n\n\n\n### š **Happy Translating!** āØ\n\n[](https://github.com/yourusername)\n[](https://python.org)\n[](https://github.com)\n\nā **Star this repo if you find it helpful!** ā\n\n
\n"}, "fd616fbefeb76c0dc128a96d10723fd1822e67cc": {"t": 1785772118.4566224, "n": 3005, "h": "e04092dc76f384a7", "c": "# PO File Translator\n\nA tool for automating the translation of PO (Portable Object) files using DeepL API.\n\n## Author\n\nAdalberto H. Vega\n\n## Description\n\nThis project provides a set of scripts to automate the translation of PO files commonly used in software localization. It uses the DeepL API for high-quality translations and maintains the formatting of the original text, including HTML tags.\n\n## Features\n\n- Automated translation of untranslated entries in PO files\n- Preserves HTML formatting and tags\n- Progress bar showing translation status\n- Error handling for failed translations\n- Support for different target languages (default: Spanish)\n- Virtual environment management\n\n## Requirements\n\n- Python 3.x\n- PowerShell\n- DeepL API key\n- Virtual environment (.venv)\n\n### Python Dependencies\n\n- polib: For handling PO files\n- deepl: DeepL API client\n- python-dotenv: For environment variable management\n- tqdm: For progress bar functionality\n\n## Obtaining a DeepL API Key\n\nTo use this translation tool, you'll need a DeepL API key. Follow these steps to get started:\n\n1. **Create an Account**: Sign up at [DeepL.com](https://www.deepl.com)\n2. **Access API Keys**: Go to your account and navigate to the 'API Keys' section\n3. **Create New Key**: Click 'Create key' to generate a new API key\n4. **Choose Plan**: Select either:\n - **Free Plan**: 500,000 characters/month\n - **Pro Plan**: Unlimited translations with advanced features\n5. **Security Note**: Keep your API key confidential and never expose it in publicly distributed code\n\nFor more details, visit the [DeepL API Documentation](https://developers.deepl.com/docs/getting-started/auth)\n\n## Setup\n\n1. Clone the repository\n2. Create a virtual environment:\n\n ```powershell\n python -m venv .venv\n ```\n\n3. Activate the virtual environment:\n\n ```powershell\n .\\.venv\\Scripts\\Activate.ps1\n ```\n\n4. Install dependencies:\n\n ```powershell\n pip install -r requirements.txt\n ```\n\n5. Create a `.env` file in the project root with your DeepL API key:\n\n ```env\n DEEPL_API_KEY=your-api-key-here\n ```\n\n## Usage\n\n### Basic Translation\n\nTo translate a PO file:\n\n```powershell\n.\\trans-po.ps1 -filename \"path\\to\\your\\file.po\"\n```\n\n### Processing Files from Downloads\n\nTo process a PO file from your Downloads folder:\n\n```powershell\n.\\process-po.ps1 -FilePrefix \"your-file-prefix\"\n```\n\nFor example, if your file is named \"elementor-1142-es.po\", use:\n\n```powershell\n.\\process-po.ps1 -FilePrefix \"elementor-1142\"\n```\n\nThe script will:\n\n1. Look for the file in your Downloads folder\n2. Process the translation\n3. Save the result as \"elementor-1142-es_ES.po\" back in your Downloads folder\n\n### Output Files\n\n- Input file format: `filename-es.po`\n- Output file format: `filename-es_ES.po`\n\n### Common Issues\n\n- Make sure your `.env` file contains a valid DeepL API key\n- Virtual environment must be set up before running the scripts\n- Input files must be valid PO format files\n\n## License\n\nMIT License\n\nCopyright (c) 2024 Adalberto H. Vega\n"}, "d2ac43e3feaf6fe6fb23764fb92f530fd526be91": {"t": 1785772119.5952759, "n": 2299, "h": "0559afe022dbb813", "c": "# PO File Translator\n\nA tool for automating the translation of PO (Portable Object) files using DeepL API.\n\n## Author\n\nAdalberto H. Vega\n\n## Description\n\nThis project provides a set of scripts to automate the translation of PO files commonly used in software localization. It uses the DeepL API for high-quality translations and maintains the formatting of the original text, including HTML tags.\n\n## Features\n\n- Automated translation of untranslated entries in PO files\n- Preserves HTML formatting and tags\n- Progress bar showing translation status\n- Error handling for failed translations\n- Support for different target languages (default: Spanish)\n- Virtual environment management\n\n## Requirements\n\n- Python 3.x\n- PowerShell\n- DeepL API key\n- Virtual environment (.venv)\n\n### Python Dependencies\n\n- polib: For handling PO files\n- deepl: DeepL API client\n- python-dotenv: For environment variable management\n- tqdm: For progress bar functionality\n\n## Setup\n\n1. Clone the repository\n2. Create a virtual environment:\n\n ```powershell\n python -m venv .venv\n ```\n\n3. Activate the virtual environment:\n\n ```powershell\n .\\.venv\\Scripts\\Activate.ps1\n ```\n\n4. Install dependencies:\n\n ```powershell\n pip install -r requirements.txt\n ```\n\n5. Create a `.env` file in the project root with your DeepL API key:\n\n ```env\n DEEPL_API_KEY=your-api-key-here\n ```\n\n## Usage\n\n### Basic Translation\n\nTo translate a PO file:\n\n```powershell\n.\\trans-po.ps1 -filename \"path\\to\\your\\file.po\"\n```\n\n### Processing Files from Downloads\n\nTo process a PO file from your Downloads folder:\n\n```powershell\n.\\process-po.ps1 -FilePrefix \"your-file-prefix\"\n```\n\nFor example, if your file is named \"elementor-1142-es.po\", use:\n\n```powershell\n.\\process-po.ps1 -FilePrefix \"elementor-1142\"\n```\n\nThe script will:\n\n1. Look for the file in your Downloads folder\n2. Process the translation\n3. Save the result as \"elementor-1142-es_ES.po\" back in your Downloads folder\n\n### Output Files\n\n- Input file format: `filename-es.po`\n- Output file format: `filename-es_ES.po`\n\n### Common Issues\n\n- Make sure your `.env` file contains a valid DeepL API key\n- Virtual environment must be set up before running the scripts\n- Input files must be valid PO format files\n\n## License\n\nMIT License\n\nCopyright (c) 2024 Adalberto H. Vega\n"}}}}