{"id":15435501,"url":"https://github.com/topce/auto-translate-json-library","last_synced_at":"2026-01-04T22:16:27.234Z","repository":{"id":59144758,"uuid":"508997537","full_name":"topce/auto-translate-json-library","owner":"topce","description":"This project is used in Auto Translate JSON vs code extension : https://marketplace.visualstudio.com/items?itemName=JeffJorczak.auto-translate-json ","archived":false,"fork":false,"pushed_at":"2025-01-26T19:57:39.000Z","size":393,"stargazers_count":4,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-23T11:38:10.493Z","etag":null,"topics":["angular","auto","aws-translate","comand-line","deepl-translator","flutter","google-tr","json","ngx-translate","openai-translate","rest-api","translation","transloco"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/auto-translate-json-library","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/topce.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2022-06-30T08:33:06.000Z","updated_at":"2025-01-26T19:55:46.000Z","dependencies_parsed_at":"2024-04-02T10:48:57.354Z","dependency_job_id":"9db23473-c269-4be9-9f83-cbdd4de811d1","html_url":"https://github.com/topce/auto-translate-json-library","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topce%2Fauto-translate-json-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topce%2Fauto-translate-json-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topce%2Fauto-translate-json-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topce%2Fauto-translate-json-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/topce","download_url":"https://codeload.github.com/topce/auto-translate-json-library/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241126954,"owners_count":19914113,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["angular","auto","aws-translate","comand-line","deepl-translator","flutter","google-tr","json","ngx-translate","openai-translate","rest-api","translation","transloco"],"created_at":"2024-10-01T18:44:52.290Z","updated_at":"2026-01-04T22:16:27.222Z","avatar_url":"https://github.com/topce.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Auto Translate JSON Library\r\n\r\nThis project is used in, (and refactored from) excellent VS Code extension\r\nAuto Translate JSON\r\n\u003chttps://marketplace.visualstudio.com/items?itemName=JeffJorczak.auto-translate-json\u003e\r\n\r\nIt opens possibility to use Auto Translation JSON\r\nnot just in VS Code but as a library and command line interface.\r\n\r\nYou can use Azure, AWS, Google, DeepL, OpenAI or\r\nlocal OpenAI compatible REST API\r\nfor example [ollama](https://ollama.com/) \r\nbecause it is compatible with OpenAI https://ollama.com/blog/openai-compatibility\r\n\r\n## πŸš€ Version 2.0.0 - Major Release\r\n\r\nThis major release brings comprehensive improvements including:\r\n- **ES Modules support** for modern JavaScript compatibility\r\n- **Enhanced validation system** with detailed error reporting and recovery\r\n- **Expanded format support** with robust handling for all major translation formats\r\n- **Complete demo system** with interactive examples\r\n- **Comprehensive test suite** with 100% format handler coverage\r\n- **Security updates** for all dependencies\r\n\r\n## Use as Library\r\n\r\n```shell\r\nnpm i auto-translate-json-library\r\n```\r\n\r\n### Basic Usage\r\n\r\n```typescript\r\nimport { translate, Configuration } from 'auto-translate-json-library';\r\n\r\nconst config: Configuration = {\r\n translationKeyInfo: {\r\n kind: 'google',\r\n apiKey: 'your-google-api-key'\r\n },\r\n sourceLocale: 'en',\r\n mode: 'file' // or 'folder'\r\n};\r\n\r\nconst pivotTranslation = \"./translations/en.json\";\r\nawait translate(pivotTranslation, config);\r\n// Creates translated files (e.g., fr.json, es.json) in the same directory\r\n```\r\n\r\n### Advanced Configuration\r\n\r\n```typescript\r\nimport { translate, Configuration } from 'auto-translate-json-library';\r\n\r\nconst config: Configuration = {\r\n // Translation service configuration\r\n translationKeyInfo: {\r\n kind: 'openai', // 'google' | 'aws' | 'azure' | 'deepLPro' | 'deepLFree' | 'openai'\r\n apiKey: 'your-api-key',\r\n // OpenAI-specific options\r\n baseUrl: 'https://api.openai.com/v1', // or local Ollama: 'http://localhost:11434/v1'\r\n model: 'gpt-4', // or local model: 'qwen2.5:14b'\r\n maxTokens: 1000,\r\n temperature: 0.3\r\n },\r\n \r\n // Processing options\r\n sourceLocale: 'en',\r\n mode: 'folder', // Process entire folder structure\r\n format: 'auto', // Auto-detect or specify: 'json', 'xml', 'yaml', etc.\r\n \r\n // Translation behavior\r\n keepTranslations: 'keep', // 'keep' | 'retranslate'\r\n keepExtraTranslations: 'remove', // 'keep' | 'remove'\r\n \r\n // Delimiters for interpolation variables\r\n startDelimiter: '{{',\r\n endDelimiter: '}}',\r\n \r\n // Keys to ignore (e.g., metadata keys)\r\n ignorePrefix: '@@'\r\n};\r\n\r\nawait translate('./translations/en.json', config);\r\n```\r\n\r\n### Translation Service Examples\r\n\r\n#### Google Translate\r\n```typescript\r\nconst config: Configuration = {\r\n translationKeyInfo: {\r\n kind: 'google',\r\n apiKey: process.env.GOOGLE_API_KEY\r\n },\r\n sourceLocale: 'en'\r\n};\r\n```\r\n\r\n#### OpenAI (GPT-4.1 mini)\r\n```typescript\r\nconst config: Configuration = {\r\n translationKeyInfo: {\r\n kind: 'openai',\r\n apiKey: process.env.OPENAI_API_KEY,\r\n model: 'gpt-4.1-mini', // Best balance of quality and cost for translations\r\n maxTokens: 1000,\r\n temperature: 0.1 // Lower for more consistent translations\r\n },\r\n sourceLocale: 'en'\r\n};\r\n```\r\n\r\n#### Local AI (Ollama)\r\n```typescript\r\nconst config: Configuration = {\r\n translationKeyInfo: {\r\n kind: 'openai',\r\n apiKey: 'ollama', // Placeholder for local usage\r\n baseUrl: 'http://localhost:11434/v1',\r\n model: 'qwen2.5:14b', // Recommended model for high-quality translations\r\n maxTokens: 512\r\n },\r\n sourceLocale: 'en'\r\n};\r\n```\r\n\r\n#### AWS Translate\r\n```typescript\r\nconst config: Configuration = {\r\n translationKeyInfo: {\r\n kind: 'aws',\r\n accessKeyId: process.env.AWS_ACCESS_KEY_ID,\r\n secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,\r\n region: 'us-east-1'\r\n },\r\n sourceLocale: 'en'\r\n};\r\n```\r\n\r\n#### Azure Translator\r\n```typescript\r\nconst config: Configuration = {\r\n translationKeyInfo: {\r\n kind: 'azure',\r\n apiKey: process.env.AZURE_TRANSLATOR_KEY,\r\n region: 'eastus'\r\n },\r\n sourceLocale: 'en'\r\n};\r\n```\r\n\r\n#### DeepL\r\n```typescript\r\n// DeepL Pro\r\nconst config: Configuration = {\r\n translationKeyInfo: {\r\n kind: 'deepLPro',\r\n apiKey: process.env.DEEPL_PRO_API_KEY\r\n },\r\n sourceLocale: 'en'\r\n};\r\n\r\n// DeepL Free\r\nconst configFree: Configuration = {\r\n translationKeyInfo: {\r\n kind: 'deepLFree',\r\n apiKey: process.env.DEEPL_FREE_API_KEY\r\n },\r\n sourceLocale: 'en'\r\n};\r\n```\r\n\r\n## Use as Command Line Tool\r\n\r\nFirst install it:\r\n\r\n```shell\r\nnpm i auto-translate-json-library\r\n```\r\n\r\n### Global Installation (Recommended)\r\n\r\nInstall globally for easier access:\r\n\r\n```shell\r\nnpm install -g auto-translate-json-library\r\n```\r\n\r\nThen use the convenient `atj` command:\r\n\r\n```shell\r\natj translations/en.json -e google -s en\r\n```\r\n\r\nYou can also use it with npx:\r\n\r\n```shell\r\nnpx auto-translate-json-library translations/en.json -e google -s en\r\n```\r\n\r\n### CLI Examples with Modern Translation Services\r\n\r\n#### Google Translate\r\n```shell\r\n# Single file translation\r\natj translations/en.json -e google -s en\r\n\r\n# Folder translation (translates all supported files)\r\natj translations/ -e google -s en -m folder\r\n\r\n# Specific format override\r\natj config/app.yaml -e google -s en --format yaml\r\n```\r\n\r\n#### OpenAI (GPT-4.1 mini/GPT-4o)\r\n```shell\r\n# Using GPT-4.1 mini for best balance of quality and cost (recommended)\r\natj translations/en.json -e openai -s en\r\n\r\n# Using GPT-4o for higher quality translations\r\nATJ_OPEN_AI_MODEL=gpt-4o atj translations/en.json -e openai -s en\r\n\r\n# Custom temperature for more creative translations\r\nATJ_OPEN_AI_TEMPERATURE=0.7 atj translations/en.json -e openai -s en\r\n```\r\n\r\n#### Local AI with Ollama\r\n```shell\r\n# Using Qwen2.5 model (recommended for high-quality translations)\r\nATJ_OPEN_AI_BASE_URL=http://localhost:11434/v1 \\\r\nATJ_OPEN_AI_MODEL=qwen2.5:14b \\\r\nATJ_OPEN_AI_SECRET_KEY=ollama \\\r\natj translations/en.json -e openai -s en\r\n\r\n# Alternative: Using smaller model for faster processing\r\nATJ_OPEN_AI_BASE_URL=http://localhost:11434/v1 \\\r\nATJ_OPEN_AI_MODEL=qwen2.5:7b \\\r\nATJ_OPEN_AI_SECRET_KEY=ollama \\\r\natj translations/en.json -e openai -s en\r\n```\r\n\r\n#### AWS Translate\r\n```shell\r\n# Basic AWS translation\r\natj translations/en.json -e aws -s en\r\n\r\n# Specify AWS region\r\nATJ_AWS_REGION=eu-west-1 atj translations/en.json -e aws -s en\r\n```\r\n\r\n#### Azure Translator\r\n```shell\r\n# Basic Azure translation\r\natj translations/en.json -e azure -s en\r\n\r\n# Specify Azure region\r\nATJ_AZURE_REGION=westeurope atj translations/en.json -e azure -s en\r\n```\r\n\r\n#### DeepL\r\n```shell\r\n# DeepL Pro (higher quality, more languages)\r\natj translations/en.json -e deepLPro -s en\r\n\r\n# DeepL Free (limited usage)\r\natj translations/en.json -e deepLFree -s en\r\n```\r\n\r\n### File vs Folder Mode\r\n\r\n#### File Mode (Default)\r\nTranslates a single file and creates translated versions in the same directory:\r\n\r\n```shell\r\n# Input: translations/en.json\r\n# Output: translations/fr.json, translations/es.json, etc.\r\natj translations/en.json -e google -s en -m file\r\n```\r\n\r\n#### Folder Mode\r\nRecursively processes all supported files in a directory structure:\r\n\r\n```shell\r\n# Processes all translation files in the folder tree\r\natj translations/ -e google -s en -m folder\r\n\r\n# Example structure:\r\n# translations/\r\n# β”œβ”€β”€ en/\r\n# β”‚ β”œβ”€β”€ common.json\r\n# β”‚ β”œβ”€β”€ errors.yaml\r\n# β”‚ └── mobile.properties\r\n# β”œβ”€β”€ fr/ # ← Created automatically\r\n# β”‚ β”œβ”€β”€ common.json\r\n# β”‚ β”œβ”€β”€ errors.yaml\r\n# β”‚ └── mobile.properties\r\n# └── es/ # ← Created automatically\r\n# β”œβ”€β”€ common.json\r\n# β”œβ”€β”€ errors.yaml\r\n# └── mobile.properties\r\n```\r\n\r\n### Format-Specific Examples\r\n\r\n#### Android Development\r\n```shell\r\n# Android strings.xml files\r\natj res/values/strings.xml -e google -s en --format android-xml\r\n\r\n# Folder mode for complete Android project\r\natj res/values/ -e google -s en -m folder --format android-xml\r\n```\r\n\r\n#### Flutter Development\r\n```shell\r\n# Flutter ARB files\r\natj lib/l10n/app_en.arb -e google -s en --format arb\r\n\r\n# Process all ARB files in l10n folder\r\natj lib/l10n/ -e google -s en -m folder --format arb\r\n```\r\n\r\n#### Web Development\r\n```shell\r\n# JSON translation files\r\natj src/assets/i18n/en.json -e openai -s en\r\n\r\n# YAML configuration files\r\natj config/locales/en.yaml -e google -s en --format yaml\r\n\r\n# Properties files (Java/Spring)\r\natj src/main/resources/messages_en.properties -e aws -s en --format properties\r\n```\r\n\r\n#### Game Development\r\n```shell\r\n# CSV files for game localization\r\natj assets/localization/strings.csv -e deepLPro -s en --format csv\r\n\r\n# XML-based game configs\r\natj data/strings/en.xml -e google -s en --format xml\r\n```\r\n\r\nDo not forget to set translation engine parameters in environment variables or .env file.\r\n\r\n## Demo and Examples\r\n\r\nThe project includes a comprehensive demo system with examples for all supported formats and both translation modes:\r\n\r\n### File Mode Demo (demo/)\r\nIndividual translation files - one file per language:\r\n```shell\r\ncd demo\r\nnpm install\r\nnode run-demo.js\r\n```\r\n\r\n### Folder Mode Demo (demo-folder/)\r\nLanguage-organized directories - multiple files per language:\r\n```shell\r\ncd demo-folder\r\nnpm install\r\nnode run-demo.js\r\n```\r\n\r\nBoth demos support:\r\n- **Local AI translation** using Ollama (recommended for testing)\r\n- **Cloud translation services** (Google, OpenAI, AWS, Azure, DeepL)\r\n- **All supported formats** (JSON, XML, YAML, Properties, ARB, PO, CSV)\r\n- **Interactive examples** with real translation results\r\n\r\nChoose the demo that matches your project structure:\r\n- **File mode**: Simple projects with one file per language (`en.json`, `fr.json`)\r\n- **Folder mode**: Complex projects with multiple files per language (`en/common.json`, `fr/common.json`)\r\n\r\nThis will run translations on sample files in multiple formats (JSON, XML, YAML, ARB, PO, Properties, CSV) using the local Ollama setup with the `qwen2.5:14b` model and show the results.\r\n\r\n## Contribute\r\n\r\nClone repo and use the following commands:\r\n\r\n1. Install ollama and run `ollama run llama2`\r\n2. Rename `ollama.env` to `.env`\r\n3. Install dependencies and build project:\r\n\r\n```shell\r\nnpm i\r\nnpm run build\r\nnode ./build/src/index.js --pivotTranslation=./tests/translations/en.json\r\n```\r\n\r\nAfter some time you should see es.json file with translation.\r\n\r\n### Development Workflow\r\n\r\n```shell\r\n# Install dependencies\r\nnpm install\r\n\r\n# Run tests\r\nnpm test\r\n\r\n# Run tests with coverage\r\nnpm run test:coverage\r\n\r\n# Lint and format code\r\nnpm run lint\r\nnpm run format-fix\r\n\r\n# Build project\r\nnpm run build\r\n\r\n# Run demo (file mode)\r\ncd demo \u0026\u0026 node run-demo.js\r\n\r\n# Run demo (folder mode)\r\ncd demo-folder \u0026\u0026 node run-demo.js\r\n```\r\n\r\n## Multi-Format Support\r\n\r\nThis tool supports a comprehensive range of translation file formats with automatic format detection and validation.\r\n\r\n### Supported Formats Overview\r\n\r\n| Format | Extension | Use Case | Auto-Detection |\r\n|--------|-----------|----------|----------------|\r\n| **JSON** | `.json` | Web apps, React, Vue, Angular | βœ… |\r\n| **ARB** | `.arb` | Flutter applications | βœ… |\r\n| **Android XML** | `.xml` | Android apps (strings.xml) | βœ… |\r\n| **iOS XML** | `.xml` | iOS apps (plist format) | βœ… |\r\n| **Generic XML** | `.xml` | Custom XML structures | βœ… |\r\n| **XLIFF** | `.xlf`, `.xliff` | Translation exchange | βœ… |\r\n| **XMB/XTB** | `.xmb`, `.xtb` | Google i18n format | βœ… |\r\n| **GNU gettext** | `.po`, `.pot` | Linux/Unix applications | βœ… |\r\n| **YAML** | `.yaml`, `.yml` | Configuration files | βœ… |\r\n| **Properties** | `.properties` | Java applications | βœ… |\r\n| **CSV** | `.csv` | Spreadsheet-based | βœ… |\r\n| **TSV** | `.tsv` | Tab-separated values | βœ… |\r\n\r\n### Format Detection\r\n\r\nThe tool automatically detects file formats using:\r\n1. **File extension** (primary method)\r\n2. **Content analysis** (fallback for ambiguous cases)\r\n3. **Manual override** using `--format` parameter\r\n\r\n```shell\r\n# Auto-detection (recommended)\r\natj translations/messages.json -e google\r\n\r\n# Manual format override\r\natj translations/data.txt --format json -e google\r\n\r\n# List all supported formats\r\natj --list-formats\r\n```\r\n\r\n### Detailed Format Support\r\n\r\n#### JSON-based Formats\r\n\r\n**Standard JSON**\r\n```json\r\n{\r\n \"welcome\": \"Welcome to our app\",\r\n \"user\": {\r\n \"name\": \"Name\",\r\n \"email\": \"Email address\"\r\n }\r\n}\r\n```\r\n\r\n**Flutter ARB (Application Resource Bundle)**\r\n```json\r\n{\r\n \"@@locale\": \"en\",\r\n \"welcome\": \"Welcome to our app\",\r\n \"@welcome\": {\r\n \"description\": \"Welcome message for new users\"\r\n },\r\n \"userCount\": \"{count, plural, =0{No users} =1{One user} other{{count} users}}\",\r\n \"@userCount\": {\r\n \"description\": \"Number of users\",\r\n \"placeholders\": {\r\n \"count\": {\r\n \"type\": \"int\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n#### XML-based Formats\r\n\r\n**Android strings.xml**\r\n```xml\r\n\u003cresources xmlns:android=\"http://schemas.android.com/apk/res/android\"\u003e\r\n \u003cstring name=\"app_name\"\u003eMy App\u003c/string\u003e\r\n \u003cstring name=\"welcome\"\u003eWelcome\u003c/string\u003e\r\n \u003cstring name=\"not_translatable\" translatable=\"false\"\u003eDEBUG_MODE\u003c/string\u003e\r\n \r\n \u003c!-- Resource groups --\u003e\r\n \u003cgroup name=\"errors\"\u003e\r\n \u003cstring name=\"network_error\"\u003eNetwork connection failed\u003c/string\u003e\r\n \u003cstring name=\"validation_error\"\u003ePlease check your input\u003c/string\u003e\r\n \u003c/group\u003e\r\n \r\n \u003c!-- CDATA sections preserved --\u003e\r\n \u003cstring name=\"formatted_text\"\u003e\u003c![CDATA[This is \u003cb\u003ebold\u003c/b\u003e text]]\u003e\u003c/string\u003e\r\n\u003c/resources\u003e\r\n```\r\n\r\n**iOS plist XML**\r\n```xml\r\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\r\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\r\n\u003cplist version=\"1.0\"\u003e\r\n\u003cdict\u003e\r\n \u003ckey\u003eapp_name\u003c/key\u003e\r\n \u003cstring\u003eMy iOS App\u003c/string\u003e\r\n \u003ckey\u003ewelcome_message\u003c/key\u003e\r\n \u003cstring\u003eWelcome to iOS!\u003c/string\u003e\r\n\u003c/dict\u003e\r\n\u003c/plist\u003e\r\n```\r\n\r\n**Generic XML (Auto-flattened)**\r\n```xml\r\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\r\n\u003ctranslations\u003e\r\n \u003cmessages\u003e\r\n \u003cgreeting\u003eHello World\u003c/greeting\u003e\r\n \u003cfarewell\u003eGoodbye\u003c/farewell\u003e\r\n \u003c/messages\u003e\r\n \u003clabels\u003e\r\n \u003csubmit\u003eSubmit\u003c/submit\u003e\r\n \u003ccancel\u003eCancel\u003c/cancel\u003e\r\n \u003c/labels\u003e\r\n\u003c/translations\u003e\r\n```\r\n*Becomes: `messages.greeting: \"Hello World\"`, `labels.submit: \"Submit\"`*\r\n\r\n#### Text-based Formats\r\n\r\n**GNU gettext PO files**\r\n```po\r\n# Comment preserved\r\nmsgid \"hello\"\r\nmsgstr \"Hello\"\r\n\r\nmsgid \"goodbye\"\r\nmsgstr \"Goodbye\"\r\n\r\n# Plural forms supported\r\nmsgid \"item\"\r\nmsgid_plural \"items\"\r\nmsgstr[0] \"item\"\r\nmsgstr[1] \"items\"\r\n```\r\n\r\n**YAML translation files**\r\n```yaml\r\n# Comments preserved\r\ngreetings:\r\n hello: \"Hello\"\r\n goodbye: \"Goodbye\"\r\nnavigation:\r\n home: \"Home\"\r\n about: \"About\"\r\n # Nested structures supported\r\n menu:\r\n file: \"File\"\r\n edit: \"Edit\"\r\n```\r\n\r\n**Java Properties files**\r\n```properties\r\n# Application messages\r\napp.title=My Application\r\napp.welcome=Welcome to our application\r\n\r\n# Unicode escaping supported\r\napp.copyright=Β© 2024 My Company\r\n\r\n# Placeholders preserved\r\nuser.greeting=Hello, {0}!\r\n```\r\n\r\n#### Tabular Formats\r\n\r\n**CSV files**\r\n```csv\r\nkey,en,fr,es\r\nwelcome,\"Welcome\",\"Bienvenue\",\"Bienvenido\"\r\ngoodbye,\"Goodbye\",\"Au revoir\",\"AdiΓ³s\"\r\n```\r\n\r\n**TSV files**\r\n```tsv\r\nkey\ten\tfr\tes\r\nwelcome\tWelcome\tBienvenue\tBienvenido\r\ngoodbye\tGoodbye\tAu revoir\tAdiΓ³s\r\n```\r\n\r\n### Format-Specific Features\r\n\r\n#### XML Formats\r\n- **Preserve attributes**: `translatable=\"false\"`, namespaces\r\n- **Maintain structure**: Comments, CDATA sections, processing instructions\r\n- **Android support**: Resource groups, plurals, string arrays\r\n- **iOS support**: Plist dictionary structure with key-value pairs\r\n- **Generic XML**: Automatic structure flattening for any XML format\r\n- **Validation**: Robust malformed XML detection and error reporting\r\n\r\n#### XLIFF Support\r\n- **Version compatibility**: XLIFF 1.2 and 2.x support\r\n- **Translation states**: Maintain workflow information (new, translated, approved)\r\n- **Metadata preservation**: Notes, comments, and translation metadata\r\n- **Segmentation**: Support for complex translation units\r\n\r\n#### GNU gettext (PO/POT)\r\n- **Plural forms**: Complete plural form handling for all languages\r\n- **Context support**: msgctxt for disambiguation\r\n- **Comments**: Preserve translator and extracted comments\r\n- **Fuzzy translations**: Handle fuzzy markers appropriately\r\n\r\n#### ARB (Flutter)\r\n- **ICU message format**: Complete support for plurals, selects, and formatting\r\n- **Metadata preservation**: Descriptions, placeholders, and examples\r\n- **Locale inheritance**: Proper locale fallback handling\r\n\r\n#### Properties Files\r\n- **Unicode escaping**: Automatic handling of Unicode characters\r\n- **Different encodings**: Support for various character encodings\r\n- **Placeholder preservation**: Maintain {0}, {1} style placeholders\r\n\r\n#### CSV/TSV Files\r\n- **Configurable columns**: Flexible column mapping and headers\r\n- **Multi-language support**: Handle multiple target languages in one file\r\n- **Encoding detection**: Automatic character encoding detection\r\n- **Quoted fields**: Proper handling of quoted and escaped content\r\n\r\n### Usage Examples by Format\r\n\r\n```shell\r\n# JSON files (auto-detected)\r\natj translations/en.json -e google\r\n\r\n# Android strings.xml\r\natj res/values/strings.xml -e aws --format android-xml\r\n\r\n# Flutter ARB files\r\natj lib/l10n/app_en.arb -e azure --format arb\r\n\r\n# XLIFF files\r\natj locales/messages.xlf -e deepLPro --format xliff\r\n\r\n# GNU gettext PO files\r\natj locales/messages.po -e openai --format po\r\n\r\n# YAML files\r\natj config/translations.yaml -e google --format yaml\r\n\r\n# Properties files\r\natj messages_en.properties -e aws --format properties\r\n\r\n# CSV files with custom structure\r\natj data/translations.csv -e google --format csv\r\n\r\n# List all supported formats\r\natj --list-formats\r\n```\r\n\r\n## Translation Service Setup Guides\r\n\r\nThe library supports multiple translation services. Choose the one that best fits your needs and follow the setup guide below.\r\n\r\n### 🌐 Google Translate (Recommended for General Use)\r\n\r\n**Best for**: High-quality translations, wide language support, reliable service\r\n\r\n#### Setup Steps:\r\n1. **Create Google Cloud Project**:\r\n - Go to [Google Cloud Console](https://console.cloud.google.com/)\r\n - Create a new project or select existing one\r\n - Enable the Cloud Translation API\r\n\r\n2. **Get API Key**:\r\n - Go to APIs \u0026 Services \u003e Credentials\r\n - Click \"Create Credentials\" \u003e \"API Key\"\r\n - Copy your API key\r\n\r\n3. **Configure Environment**:\r\n ```bash\r\n # Copy the Google environment template\r\n cp google.env .env\r\n \r\n # Edit .env and replace your_google_api_key_here with your actual API key\r\n ```\r\n\r\n4. **Usage**:\r\n ```bash\r\n atj translations/en.json -e google -s en\r\n ```\r\n\r\n#### Pricing:\r\n- $20 per 1M characters\r\n- Free tier: $300 credit for new users\r\n\r\n---\r\n\r\n### πŸ€– OpenAI (Best for Context-Aware Translations)\r\n\r\n**Best for**: Context-aware translations, technical content, creative translations\r\n\r\n#### Setup Steps:\r\n1. **Get OpenAI API Key**:\r\n - Go to [OpenAI Platform](https://platform.openai.com/)\r\n - Create account and add billing information\r\n - Go to API Keys section and create new key\r\n\r\n2. **Configure Environment**:\r\n ```bash\r\n # Copy the OpenAI environment template\r\n cp openai.env .env\r\n \r\n # Edit .env and replace your_openai_api_key_here with your actual API key\r\n ```\r\n\r\n3. **Usage**:\r\n ```bash\r\n # Using GPT-4.1 mini (best balance of quality and cost - recommended)\r\n atj translations/en.json -e openai -s en\r\n \r\n # Using GPT-4o (higher quality, moderate cost)\r\n ATJ_OPEN_AI_MODEL=gpt-4o atj translations/en.json -e openai -s en\r\n ```\r\n\r\n#### Model Recommendations for Translation:\r\n- **GPT-4.1 mini**: Best balance of quality and cost (recommended for most translations)\r\n- **GPT-4o mini**: Good quality, very cost-effective (legacy but still available)\r\n- **GPT-4.1**: Higher quality for complex translations, more expensive\r\n- **GPT-4o**: Excellent multimodal capabilities, moderate cost\r\n\r\n#### Pricing (Approximate):\r\n- GPT-4.1 mini: ~$0.15/1M input tokens, ~$0.60/1M output tokens (most cost-effective)\r\n- GPT-4o mini: ~$0.15/1M input tokens, ~$0.60/1M output tokens\r\n- GPT-4.1: ~$2.00/1M input tokens, ~$8.00/1M output tokens\r\n- GPT-4o: ~$2.50/1M input tokens, ~$10.00/1M output tokens\r\n\r\n---\r\n\r\n### 🏠 Local AI with Ollama (Free \u0026 Private)\r\n\r\n**Best for**: Privacy-sensitive projects, offline usage, no API costs\r\n\r\n#### Setup Steps:\r\n1. **Install Ollama**:\r\n ```bash\r\n # macOS\r\n brew install ollama\r\n \r\n # Linux\r\n curl -fsSL https://ollama.com/install.sh | sh\r\n \r\n # Windows: Download from https://ollama.com/\r\n ```\r\n\r\n2. **Download Model**:\r\n ```bash\r\n # High-quality model (recommended)\r\n ollama pull qwen2.5:14b\r\n \r\n # Faster alternative\r\n ollama pull qwen2.5:7b\r\n ```\r\n\r\n3. **Start Ollama**:\r\n ```bash\r\n ollama serve\r\n ```\r\n\r\n4. **Configure Environment**:\r\n ```bash\r\n # Copy the Ollama environment template\r\n cp ollama.env .env\r\n ```\r\n\r\n5. **Usage**:\r\n ```bash\r\n atj translations/en.json -e openai -s en\r\n ```\r\n\r\n#### Model Recommendations:\r\n- **qwen2.5:14b**: Best quality (8GB RAM required)\r\n- **qwen2.5:7b**: Good balance (4GB RAM required)\r\n- **qwen2.5:3b**: Fastest (2GB RAM required)\r\n\r\n---\r\n\r\n### ☁️ AWS Translate (Best for AWS Ecosystem)\r\n\r\n**Best for**: AWS-integrated projects, enterprise use, batch processing\r\n\r\n#### Setup Steps:\r\n1. **Create AWS Account**:\r\n - Go to [AWS Console](https://aws.amazon.com/)\r\n - Create account or sign in\r\n\r\n2. **Create IAM User**:\r\n - Go to IAM \u003e Users \u003e Create User\r\n - Attach policy: `TranslateFullAccess`\r\n - Create access key for programmatic access\r\n\r\n3. **Configure Environment**:\r\n ```bash\r\n # Copy the AWS environment template\r\n cp aws.env .env\r\n \r\n # Edit .env and replace with your actual AWS credentials\r\n ```\r\n\r\n4. **Usage**:\r\n ```bash\r\n atj translations/en.json -e aws -s en\r\n ```\r\n\r\n#### Pricing:\r\n- $15 per 1M characters\r\n- Free tier: 2M characters per month for 12 months\r\n\r\n---\r\n\r\n### πŸ”· Azure Translator (Best for Microsoft Ecosystem)\r\n\r\n**Best for**: Microsoft-integrated projects, enterprise use, custom models\r\n\r\n#### Setup Steps:\r\n1. **Create Azure Account**:\r\n - Go to [Azure Portal](https://portal.azure.com/)\r\n - Create account or sign in\r\n\r\n2. **Create Translator Resource**:\r\n - Search for \"Translator\" in Azure Portal\r\n - Create new Translator resource\r\n - Choose pricing tier and region\r\n - Get key and endpoint from resource\r\n\r\n3. **Configure Environment**:\r\n ```bash\r\n # Copy the Azure environment template\r\n cp azure.env .env\r\n \r\n # Edit .env and replace with your actual Azure credentials\r\n ```\r\n\r\n4. **Usage**:\r\n ```bash\r\n atj translations/en.json -e azure -s en\r\n ```\r\n\r\n#### Pricing:\r\n- Standard: $10 per 1M characters\r\n- Free tier: 2M characters per month\r\n\r\n---\r\n\r\n### 🎯 DeepL (Best Translation Quality)\r\n\r\n**Best for**: Highest quality translations, European languages, professional content\r\n\r\n#### Setup Steps:\r\n1. **Create DeepL Account**:\r\n - Go to [DeepL Pro](https://www.deepl.com/pro) or [DeepL API Free](https://www.deepl.com/pro#developer)\r\n - Choose Pro (paid) or Free plan\r\n - Get your API key from account settings\r\n\r\n2. **Configure Environment**:\r\n ```bash\r\n # Copy the DeepL environment template\r\n cp deepl.env .env\r\n \r\n # Edit .env and replace with your actual DeepL API key\r\n # Use either Pro or Free key (uncomment the appropriate line)\r\n ```\r\n\r\n3. **Usage**:\r\n ```bash\r\n # DeepL Pro\r\n atj translations/en.json -e deepLPro -s en\r\n \r\n # DeepL Free\r\n atj translations/en.json -e deepLFree -s en\r\n ```\r\n\r\n#### Pricing:\r\n- **DeepL Pro**: €5.99/month + €20 per 1M characters\r\n- **DeepL API Free**: 500,000 characters/month free\r\n\r\n---\r\n\r\n## Service Comparison\r\n\r\n| Service | Quality | Speed | Cost | Languages | Best For |\r\n|---------|---------|-------|------|-----------|----------|\r\n| **Google** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | 100+ | General use, reliability |\r\n| **OpenAI** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | 50+ | Context-aware, technical |\r\n| **Ollama** | ⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | 30+ | Privacy, offline, free |\r\n| **AWS** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | 75+ | AWS ecosystem |\r\n| **Azure** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | 90+ | Microsoft ecosystem |\r\n| **DeepL** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ | 30+ | Highest quality |\r\n\r\n## Quick Start Examples\r\n\r\n### For Web Development\r\n```bash\r\n# React/Vue/Angular projects with Google Translate\r\ncp google.env .env\r\natj src/locales/en.json -e google -s en\r\n```\r\n\r\n### For Mobile Development\r\n```bash\r\n# Flutter with DeepL for high quality\r\ncp deepl.env .env\r\natj lib/l10n/app_en.arb -e deepLPro -s en --format arb\r\n\r\n# Android with AWS\r\ncp aws.env .env\r\natj res/values/strings.xml -e aws -s en --format android-xml\r\n```\r\n\r\n### For Enterprise/Privacy\r\n```bash\r\n# Local AI for sensitive content\r\ncp ollama.env .env\r\nollama pull qwen2.5:14b\r\nollama serve\r\natj translations/en.json -e openai -s en\r\n```\r\n\r\n### For High-Quality Content\r\n```bash\r\n# OpenAI GPT-4 for technical documentation\r\ncp openai.env .env\r\natj docs/en.yaml -e openai -s en --format yaml\r\n```\r\n\r\n## CLI Parameters Reference\r\n\r\n### Basic Parameters\r\n\r\n| Parameter | Short | Description | Default | Example |\r\n|-----------|-------|-------------|---------|---------|\r\n| `--pivotTranslation` | | Source translation file/folder path | Required | `./translations/en.json` |\r\n| `--mode` | `-m` | Processing mode: `file` or `folder` | `file` | `-m folder` |\r\n| `--engine` | `-e` | Translation engine | `aws` | `-e google` |\r\n| `--sourceLocale` | `-s` | Source language code | `en` | `-s en` |\r\n| `--format` | `-f` | Force specific format | `auto-detect` | `--format yaml` |\r\n| `--help` | `-h` | Show help message | | `-h` |\r\n| `--list-formats` | | List all supported formats | | `--list-formats` |\r\n\r\n### Advanced Parameters\r\n\r\n| Parameter | Description | Values | Default |\r\n|-----------|-------------|--------|---------|\r\n| `--keepTranslations` | Handle existing translations | `keep`, `retranslate` | `keep` |\r\n| `--keepExtraTranslations` | Handle extra keys not in source | `keep`, `remove` | `remove` |\r\n| `--startDelimiter` | Variable start delimiter | Any string | `{` |\r\n| `--endDelimiter` | Variable end delimiter | Any string | `}` |\r\n| `--ignorePrefix` | Skip keys starting with prefix | Any string | (none) |\r\n\r\n### Translation Engines\r\n\r\n| Engine | Parameter Value | Description | API Required |\r\n|--------|----------------|-------------|--------------|\r\n| **Google Translate** | `google` | Google Cloud Translation API | Google API Key |\r\n| **AWS Translate** | `aws` | Amazon Translate service | AWS credentials |\r\n| **Azure Translator** | `azure` | Microsoft Translator service | Azure key + region |\r\n| **DeepL Pro** | `deepLPro` | DeepL Pro API (higher limits) | DeepL Pro API key |\r\n| **DeepL Free** | `deepLFree` | DeepL Free API (limited) | DeepL Free API key |\r\n| **OpenAI** | `openai` | GPT models for translation | OpenAI API key |\r\n\r\n### Environment Variables\r\n\r\n#### Google Translate\r\n```bash\r\nATJ_GOOGLE_API_KEY=your_google_api_key_here\r\n```\r\n\r\n#### AWS Translate\r\n```bash\r\nATJ_AWS_ACCESS_KEY_ID=your_aws_access_key\r\nATJ_AWS_SECRET_ACCESS_KEY=your_aws_secret_key\r\nATJ_AWS_REGION=us-east-1\r\n```\r\n\r\n#### Azure Translator\r\n```bash\r\nATJ_AZURE_SECRET_KEY=your_azure_translator_key\r\nATJ_AZURE_REGION=eastus\r\n```\r\n\r\n#### DeepL\r\n```bash\r\n# DeepL Pro\r\nATJ_DEEPL_PRO_SECRET_KEY=your_deepl_pro_key\r\n\r\n# DeepL Free\r\nATJ_DEEPL_FREE_SECRET_KEY=your_deepl_free_key\r\n```\r\n\r\n#### OpenAI / Local AI\r\n```bash\r\n# OpenAI (GPT-4.1 mini, GPT-4o, GPT-4.1)\r\nATJ_OPEN_AI_SECRET_KEY=your_openai_api_key\r\nATJ_OPEN_AI_BASE_URL=https://api.openai.com/v1\r\nATJ_OPEN_AI_MODEL=gpt-4.1-mini\r\nATJ_OPEN_AI_MAX_TOKENS=1000\r\nATJ_OPEN_AI_TEMPERATURE=0.1\r\nATJ_OPEN_AI_TOP_P=1.0\r\nATJ_OPEN_AI_N=1\r\nATJ_OPEN_AI_FREQUENCY_PENALTY=0\r\nATJ_OPEN_AI_PRESENCE_PENALTY=0\r\n\r\n# Local AI (Ollama, Jan.ai, etc.)\r\nATJ_OPEN_AI_SECRET_KEY=ollama\r\nATJ_OPEN_AI_BASE_URL=http://localhost:11434/v1\r\nATJ_OPEN_AI_MODEL=qwen2.5:14b\r\nATJ_OPEN_AI_MAX_TOKENS=512\r\nATJ_OPEN_AI_TEMPERATURE=0.3\r\n```\r\n\r\n#### Other Configuration\r\n```bash\r\n# Processing options\r\nATJ_START_DELIMITER={{\r\nATJ_END_DELIMITER=}}\r\nATJ_MODE=file\r\nATJ_SOURCE_LOCALE=en\r\nATJ_KEEP_TRANSLATIONS=keep\r\nATJ_KEEP_EXTRA_TRANSLATIONS=remove\r\nATJ_IGNORE_PREFIX=@@\r\n```\r\n\r\n### Complete CLI Examples\r\n\r\n#### Basic Usage\r\n```shell\r\n# Translate single JSON file with Google\r\natj translations/en.json -e google -s en\r\n\r\n# Translate folder structure with AWS\r\natj translations/ -e aws -s en -m folder\r\n\r\n# Force YAML format detection\r\natj config/app.txt --format yaml -e azure -s en\r\n```\r\n\r\n#### Advanced Usage\r\n```shell\r\n# Retranslate existing files, keep extra keys\r\natj translations/en.json -e openai -s en \\\r\n --keepTranslations retranslate \\\r\n --keepExtraTranslations keep\r\n\r\n# Custom delimiters for Vue.js i18n\r\natj src/locales/en.json -e google -s en \\\r\n --startDelimiter \"{{\" \\\r\n --endDelimiter \"}}\"\r\n\r\n# Ignore metadata keys starting with @@\r\natj lib/l10n/app_en.arb -e deepLPro -s en \\\r\n --ignorePrefix \"@@\"\r\n```\r\n\r\n#### Production Workflows\r\n```shell\r\n# Android app localization\r\natj res/values/strings.xml -e google -s en \\\r\n --format android-xml \\\r\n --keepTranslations keep\r\n\r\n# Flutter app with ARB files\r\natj lib/l10n/ -e azure -s en -m folder \\\r\n --format arb \\\r\n --keepExtraTranslations remove\r\n\r\n# Web app with nested JSON structure\r\natj src/assets/i18n/en.json -e openai -s en \\\r\n --keepTranslations retranslate \\\r\n --startDelimiter \"{\" \\\r\n --endDelimiter \"}\"\r\n\r\n# Game localization with CSV\r\natj assets/localization/strings.csv -e deepLPro -s en \\\r\n --format csv \\\r\n --keepTranslations keep\r\n```\r\n\r\nYou can also use .env file to store environment variables for easier configuration management.\r\n\r\n## Recent Improvements\r\n\r\n### Version 2.0.0 - Major Release (2025-01-04)\r\n\r\nThis major release represents a complete rewrite and enhancement of the library:\r\n\r\n#### πŸ”„ **ES Modules Migration**\r\n- Complete migration from CommonJS to ES modules\r\n- Modern JavaScript compatibility with `\"type\": \"module\"`\r\n- Updated import/export syntax throughout codebase\r\n\r\n#### πŸ›‘οΈ **Enhanced Validation System**\r\n- New comprehensive validation framework with detailed error reporting\r\n- Automatic error recovery and correction capabilities\r\n- Format-specific validation rules and error messages\r\n- Enhanced debugging and troubleshooting information\r\n\r\n#### 🎯 **Demo System**\r\n- **Dual demo modes**: File mode (`demo/`) and Folder mode (`demo-folder/`)\r\n- Interactive examples with examples for all supported formats\r\n- **Local AI integration** with Ollama for offline testing\r\n- Automated reset and run scripts for easy testing\r\n- Sample files demonstrating real-world usage patterns\r\n- Quick start examples for new users\r\n- **Comprehensive format coverage**: JSON, XML, YAML, Properties, ARB, PO, CSV\r\n\r\n#### πŸ§ͺ **Comprehensive Testing**\r\n- 100% test coverage for all format handlers\r\n- Integration tests for CLI functionality\r\n- Error handling and edge case testing\r\n- Cross-format compatibility validation\r\n\r\n#### πŸ”§ **Code Quality Improvements**\r\n- Complete codebase formatting with Biome linter\r\n- Enhanced TypeScript configurations and type safety\r\n- Improved error handling and user feedback\r\n- Optimized performance for large files\r\n\r\n#### πŸ”’ **Security Updates**\r\n- Updated all dependencies to latest secure versions\r\n- Fixed security vulnerabilities in axios and jws\r\n- Enhanced input validation and sanitization\r\n\r\n### XML Handler Enhancements (v1.5.5)\r\n\r\nThe XML handler has been significantly improved with the following features:\r\n\r\n- **Enhanced Format Detection**: Automatically detects Android, iOS, and generic XML formats even with attributes and namespaces\r\n- **Improved Validation**: Robust validation that properly identifies invalid XML structures and provides specific error messages\r\n- **Better Error Handling**: Detects malformed XML with unclosed tags and provides clear error messages\r\n- **Generic XML Flattening**: Automatically flattens nested XML structures for easier translation (e.g., `\u003cmessages\u003e\u003cgreeting\u003eHello\u003c/greeting\u003e\u003c/messages\u003e` becomes `messages.greeting: \"Hello\"`)\r\n- **Attribute Preservation**: Maintains XML attributes like `translatable=\"false\"` and namespace declarations\r\n- **Round-trip Translation**: Ensures translated content can be serialized back to valid XML while preserving structure\r\n\r\n### Supported XML Structures\r\n\r\n1. **Android strings.xml**: Full support for resource groups, CDATA sections, and Android-specific attributes\r\n2. **iOS plist XML**: Complete support for Apple's property list format with key-value pairs\r\n3. **Generic XML**: Automatic structure detection and flattening for any XML translation format\r\n\r\n### Debug and Development\r\n\r\n1. Create .env file in main folder with the desired key/keys from **ENVIRONMENT VARIABLES** section\r\n2. Add also in .env source locale `ATJ_SOURCE_LOCALE=en` to test from en\r\n3. Run: `npm run debug`\r\n\r\n### Testing\r\n\r\nRun the comprehensive test suite:\r\n\r\n```shell\r\n# Run all tests\r\nnpm test\r\n\r\n# Run tests with coverage report\r\nnpm run test:coverage\r\n\r\n# Run tests in watch mode (for development)\r\nnpm run test:watch\r\n```\r\n\r\n### Migration from v1.x to v2.0\r\n\r\nIf upgrading from version 1.x, please note:\r\n\r\n1. **Node.js Requirements**: Ensure you're using a Node.js version that supports ES modules\r\n2. **Import Syntax**: Update any custom integrations to use ES module import syntax\r\n3. **API Changes**: Review the updated TypeScript definitions for any breaking changes\r\n4. **Testing**: Thoroughly test your specific file formats and workflows with the new version\r\n\r\nFor detailed migration assistance, see the [CHANGELOG.md](CHANGELOG.md) file.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftopce%2Fauto-translate-json-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftopce%2Fauto-translate-json-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftopce%2Fauto-translate-json-library/lists"}