{"id":21275999,"url":"https://github.com/leolabs/json-autotranslate","last_synced_at":"2025-10-07T21:25:47.152Z","repository":{"id":38272148,"uuid":"174252944","full_name":"leolabs/json-autotranslate","owner":"leolabs","description":"Translate a folder of JSON files containing translations into multiple languages.","archived":false,"fork":false,"pushed_at":"2025-03-22T09:19:12.000Z","size":711,"stargazers_count":147,"open_issues_count":24,"forks_count":46,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-06T10:14:03.331Z","etag":null,"topics":["azure-translator","deepl","google-translate","i18n","i18next","icu","localization","translation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/leolabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["leolabs"],"ko_fi":"leolabs","custom":"https://paypal.me/leolabs"}},"created_at":"2019-03-07T02:00:48.000Z","updated_at":"2025-05-01T14:08:44.000Z","dependencies_parsed_at":"2024-01-10T15:47:14.222Z","dependency_job_id":"74de23cd-feb3-4e19-877e-6ce92fe88b41","html_url":"https://github.com/leolabs/json-autotranslate","commit_stats":{"total_commits":153,"total_committers":21,"mean_commits":7.285714285714286,"dds":"0.21568627450980393","last_synced_commit":"aa7116d2f4df214ad9f944c6753bf8192fa54816"},"previous_names":["leolabs/i18next-google-translate"],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leolabs%2Fjson-autotranslate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leolabs%2Fjson-autotranslate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leolabs%2Fjson-autotranslate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leolabs%2Fjson-autotranslate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leolabs","download_url":"https://codeload.github.com/leolabs/json-autotranslate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384988,"owners_count":22062422,"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":["azure-translator","deepl","google-translate","i18n","i18next","icu","localization","translation"],"created_at":"2024-11-21T09:45:46.276Z","updated_at":"2025-10-07T21:25:42.104Z","avatar_url":"https://github.com/leolabs.png","language":"TypeScript","funding_links":["https://github.com/sponsors/leolabs","https://ko-fi.com/leolabs","https://paypal.me/leolabs"],"categories":[],"sub_categories":[],"readme":"# json-autotranslate\n\nThis tool allows you to translate a locale folder containing multiple JSON files\ninto multiple languages using Google Translate, DeepL (free/pro), Azure\nTranslator, Amazon Translate, or manually. You can either use the translation\nkeys (natural translation) or their values (key-based translation) as a source\nfor translations.\n\nIf some of the strings have already been translated, they won't be translated\nagain. This improves performance and ensures that you won't accidentally lose\nexisting translations.\n\nInterpolations (ICU: `{name}`, i18next: `{{name}}`, sprintf: `%s`) are replaced\nby placeholders (e.g. `\u003c0 /\u003e`) before being passed to the translation service,\nso their structure doesn't get mangled by the translation.\n\n## Installation\n\n```shell\n$ yarn add json-autotranslate\n# or\n$ npm i -S json-autotranslate\n```\n\n## Running json-autotranslate\n\n```shell\n$ yarn json-autotranslate\n# or\n$ npx json-autotranslate\n```\n\n### Usage Examples\n\nTranslate natural language source files located in the `locales` directory using\nGoogle Translate and delete existing keys in translated JSON files that are no\nlonger used.\n\n```shell\n$ yarn json-autotranslate -i locales -d -c service-account.json\n```\n\nManually translate key-based source files located in the `locales` directory.\n\n```shell\n$ yarn json-autotranslate -i locales -s manual\n```\n\n## Directory Structure\n\nYou can specify your `locales`/`i18n` directory structure using the\n`--directory-structure` option.\n\n### Default\n\n```\nlocales\n├── de\n├── en\n│   ├── login.json\n│   └── register.json\n├── fr\n└── it\n```\n\nIf you don't specify another source language, this tool will translate all files\nlocated in the `en` into all other languages that exist as directories. A single\nlanguage directory (e.g. `en`) should only contain JSON files. Sub-directories\nand other files will be ignored.\n\n### Ngx-translate\n\n```\ni18n\n├── de.json\n├── en.json\n├── fr.json\n└── it.json\n```\n\nIf you don't specify another source language, this tool will translate `en.json`\ninto all other languages that exist as files. The `i18n` directory should only\ncontain JSON files. Sub-directories and other files will be ignored.\n\n## File Structure\n\nThere are two ways that json-autotranslate can interpret files:\n\n- Natural Language (`natural`)\n- Key-Based (`key-based`)\n\nIf you don't specify a file structure type, json-autotranslate will\nautomatically determine the type on a per-file basis. In most cases, this is\nsufficient.\n\n### Natural Language\n\nThis is the default way that this tool will interpret your source files. The\nkeys will be used as the basis of translations. If one or more of the values in\nyour source files don't match their respective key, you'll see a warning as this\ncould indicate an inconsistency in your translations. You can fix those\ninconsistencies by passing the `--fix-inconsistencies` flag.\n\n```json\n{\n  \"Your username doesn't exist.\": \"Your username doesn't exist.\",\n  \"{email} is not a valid email address.\": \"{email} is not a valid email address.\"\n}\n```\n\n### Key-Based\n\nIf you pass use the `key-based` option (`--type key-based`), this tool will use\nthe source file's values as the basis of translations. Keys can be nested, the\nstructure will be transferred over to the translated files as well.\n\n```json\n{\n  \"ERRORS\": {\n    \"USERNAME\": \"Your username doesn't exist.\",\n    \"EMAIL\": \"{email} is not a valid email address.\"\n  },\n  \"LOGIN\": \"Login\",\n  \"FORGOT_PASSWORD\": \"Forgot password?\"\n}\n```\n\n## Available Services\n\nAs of this release, json-autotranslate offers five services:\n\n- **google-translate** (default, uses\n  [Google Translate](https://translate.google.com) to translate strings)\n- **deepl** (uses [DeepL Pro](https://deepl.com) to translate strings)\n- **deepl-free** (uses [DeepL Free](https://deepl.com) to translate strings)\n- **azure** (uses Azure's\n  [Translator Text](https://azure.microsoft.com/en-us/services/cognitive-services/translator-text-api/)\n  to translate strings)\n- **amazon-translate** (uses\n  [Amazon Translate](https://aws.amazon.com/translate/) to translate strings)\n- **OpenAI** (uses gpt-4o and can take a context file path from the context option)\n- **manual** (allows you to translate strings manually by entering them into the\n  CLI)\n- **dry-run** (outputs a list of strings that will be translated without\n  touching any files)\n\nYou can select a service using the `-s` or `--service` option. If you specify\nthe `--list-services` flag, json-autotranslate will output a list of all\navailable services.\n\n### Google Translate\n\nTo use this tool with Google Translate, you need to obtain valid credentials\nfrom Google. Follow these steps to get them:\n\n1.  [Select or create a Cloud Platform project][projects]\n2.  [Enable billing for your project][billing] (optional, I think)\n3.  [Enable the Google Cloud Translation API][enable_api]\n4.  [Set up authentication with a service account][auth] so you can access the\n    API from your local workstation\n\n[projects]: https://console.cloud.google.com/project\n[billing]: https://support.google.com/cloud/answer/6293499#enable-billing\n[enable_api]:\n  https://console.cloud.google.com/flows/enableapi?apiid=translate.googleapis.com\n[auth]: https://cloud.google.com/docs/authentication/getting-started\n\nYou can specify the location of your downloaded JSON key file using the `-c` or\n`--config` option.\n\n### DeepL\n\nTo use this tool with DeepL, you need to obtain an API key from their website.\nIf you don't have a Developer account yet, you can create one\n[here](https://www.deepl.com/en/pro.html#developer).\n\nDeepL Pro charges a fixed monthly price plus a variable fee for every 500\ntranslated characters.\n\nDeepL Free is limited to 500,000 characters translated per month.\n\nAfter you have completed your sign-up, you can pass the API key to\njson-autotranslate using the `-c` or `--config` option.\n\nThe value of the `--config` argument is a comma separated string with the\nfollowing: `appKey,formality,batchSize`.\n\nThe `formality` argument currently only works for target languages \"DE\"\n(German), \"FR\" (French), \"IT\" (Italian), \"ES\" (Spanish), \"NL\" (Dutch), \"PL\"\n(Polish), \"PT-PT\", \"PT-BR\" (Portuguese) and \"RU\" (Russian). Possible options\nare:\n\n- \"default\" (default)\n- \"more\" - for a more formal language\n- \"less\" - for a more informal language\n\nTo improve performance and prevent DeepL rate-limiting json-autotranslate\nbatches multiple tokens into a single translation request. By default, the\n`batchSize` is set to `1000`, meaning that `1000` tokens are translated at once.\nThis can be controlled by adjusting the value in the `--config` parameter. This\nvalue was chosen because the DeepL prevents the body of a request to be larger\nthan `128 KiB (128 · 1024 bytes)``. Based on experimentation, even with long\ntokens, this limit is not reached.\n\n\u003csup\u003e\u003ca href=\"https://www.deepl.com/de/docs-api/translating-text/\"\u003eReference\u003c/a\u003e\u003c/sup\u003e\n\n### Azure Translator Text\n\nTo use this tool with Azure's Translator Text, you need to obtain an API key\nfrom their website. [Sign Up](https://azure.microsoft.com/en-us/free/) for an\nAzure account if you don't have one already and\n[create a new translator instance](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation).\nYou'll get an API key soon after that which you can pass to json-autotranslate\nusing the `-c` or `--config` flag.\n\nUnless you configure a global translator instance you will need to provide a\nregion by adding it to the config string after the API key, separated by a\ncomma: `--config apiKey,region`. As of this version, the following regions are\navailable:\n\n\u003e australiaeast, brazilsouth, canadacentral, centralindia, centralus,\n\u003e centraluseuap, eastasia, eastus, eastus2, francecentral, japaneast, japanwest,\n\u003e koreacentral, northcentralus, northeurope, southcentralus, southeastasia,\n\u003e uksouth, westcentralus, westeurope, westus, westus2, and southafricanorth\n\n\u003csup\u003e\u003ca href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/translator/reference/v3-0-reference#authenticating-with-a-multi-service-resource\"\u003eReference\u003c/a\u003e\u003c/sup\u003e\n\nAs of now, the first 2M characters of translation per month are free. After that\nyou'll have to pay \\$10 per 1M characters that you translate. See their\n[pricing](https://azure.microsoft.com/en-us/pricing/details/cognitive-services/translator/)\n\n### Amazon Translate\n\n- [Create an AWS account](https://aws.amazon.com/free)\n- Create an IAM user with\n  [the permissions required for Amazon Translate](https://docs.aws.amazon.com/translate/latest/dg/translate-api-permissions-ref.html).\n  A policy file like the following should work:\n\n```\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Sid\": \"VisualEditor0\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"comprehend:DetectDominantLanguage\",\n                \"translate:TranslateText\"\n            ],\n            \"Resource\": \"*\"\n        }\n    ]\n}\n```\n\n- [Configure your AWS user credentials](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html)\n  locally, or wherever you will be running json-autotranslate. There are many\n  ways to do this, but it is best to use something like\n  [shared credentials](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-shared.html).\n  Hard coded credentials should not be used for anything beyond proof of\n  concept.\n- Create a json configuration file that defines the AWS region you want to use\n  Translate in.\n\nYou can provide a path to the json configuration file via the `--config` flag.\nYou may define any properties from\n[TranslateClientConfig](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-translate/interfaces/translateclientconfig.html)\nand they will be passed as the first argument to the\n[Translate Constructor](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-translate/classes/translate.html#constructor).\nAt a minimum, this must include the AWS region.\n\nAmazon Translate offers a free tier, but is paid after that. See their\n[pricing](https://aws.amazon.com/translate/pricing/) page for details.\n\n### Manual\n\nThis service doesn't require any configuration. You will be prompted to\ntranslate the source strings manually in the console.\n\n## Available Matchers\n\nMatchers are used to replace interpolations with placeholders before they are\nsent to the translation service. This ensures that interpolations don't get\nscrambled in the process. As of this release, json-autotranslate offers four\nmatchers for different styles of interpolation:\n\n- **icu** (default, matches [ICU MessageFormat](https://translate.google.com)\n  interpolations)\n- **i18next** (matches\n  [i18next](https://www.i18next.com/translation-function/interpolation)\n  interpolations)\n- **sprintf** (matches sprintf-style interpolations like `%s`)\n- **none** (doesn't match any interpolations)\n\nYou can select a matchers using the `-m` or `--matcher` option. If you specify\nthe `--list-matchers` flag, json-autotranslate will output a list of all\navailable matchers.\n\n## Available Options\n\n```\nOptions:\n  -i, --input \u003cinputDir\u003e                         the directory containing language directories (default: \".\")\n  --exclude \u003cexclude glob\u003e                       exclude files matching the given glob pattern\n  --cache \u003ccacheDir\u003e                             set the cache directory (default: \".json-autotranslate-cache\")\n  -l, --source-language \u003csourceLang\u003e             specify the source language (default: \"en\")\n  -t, --type \u003ckey-based|natural|auto\u003e            specify the file structure type (default: \"auto\")\n  -a, --with-arrays                              enables support for arrays in files, but removes support for keys named 0, 1, 2, etc.\n  -s, --service \u003cservice\u003e                        selects the service to be used for translation (default: \"google-translate\")\n  -g, --glossaries [glossariesDir]               set the glossaries folder to be used by DeepL. Keep empty for automatic determination of matching glossary\n  -a, --appName \u003cappName\u003e                        specify the name of your app to distinguish DeepL glossaries (if sharing an API key between multiple projects) (default: \"json-autotranslate\")\n  --context \u003ccontext\u003e                            set the context that is used by DeepL for translations, for OpenAI it is the path to the json file containing the context for each key\n  --list-services                                outputs a list of available services\n  -m, --matcher \u003cmatcher\u003e                        selects the matcher to be used for interpolations (default: \"icu\")\n  --list-matchers                                outputs a list of available matchers\n  -c, --config \u003cvalue\u003e                           supply a config parameter (e.g. path to key file) to the translation service\n  -f, --fix-inconsistencies                      automatically fixes inconsistent key-value pairs by setting the value to the key\n  -d, --delete-unused-strings                    deletes strings in translation files that don't exist in the template\n  --directory-structure \u003cdefault|ngx-translate\u003e  the locale directory structure\n  --decode-escapes                               decodes escaped HTML entities like \u0026#39; into normal UTF-8 characters\n  -o, --overwrite                                overwrite already present translations\n  -h, --help                                     display help for command\n```\n\n## Contributing\n\nIf you'd like to contribute to this project, please feel free to open a pull\nrequest.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleolabs%2Fjson-autotranslate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleolabs%2Fjson-autotranslate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleolabs%2Fjson-autotranslate/lists"}