diff --git a/README.md b/README.md index f6effd9..13c7631 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,110 @@ -

- go-json-translate -

- -

- Translate json language files / i18n locales on the spot! -

+# go-json-translate +

-This tool was made to easily translate json translations files. Front-end frameworks and CMS don't always provide a lot of translations, or any translations in some cases. This is totally understandable, but it's a major problem when you need to translate a 1000+ lines json language file. This tool can do that! + go-json-translate

-

- -[![GitHub issues](https://img.shields.io/github/issues/gmonarque/go-json-translate)](https://github.com/gmonarque/go-json-translate/issues) -[![GitHub license](https://img.shields.io/github/license/gmonarque/go-json-translate)](https://github.com/gmonarque/go-json-translate/blob/main/LICENSE) - - Personnal website - +

+ Translate JSON language files / i18n locales on the spot!

+

+ + GitHub issues + + + GitHub license +

-## Example (![United Kingdom](https://raw.githubusercontent.com/stevenrskelton/flag-icon/master/png/16/country-4x3/gb.png) -> ![France](https://raw.githubusercontent.com/stevenrskelton/flag-icon/master/png/16/country-4x3/fr.png)) -English language file (BigCommerce) +## About + +go-json-translate is a tool designed to easily translate JSON translation files. It's particularly useful for projects with large language files that need quick and efficient translation. + +## Features + +- Translate any standard JSON file using DeepL's free API +- Support for JSON files containing strings, numbers, and booleans +- Handles nested JSON files without limits +- Local database for translation caching to improve speed and reduce API calls +- Preserves variables in translated text (e.g., `hello, {name}` -> `bonjour, {name}`) +- Supports various enclosure tags: `{}`, `#{}`, `[]` + +## Example + +English (Source): ```json { - "account": { - "breadcrumb": "Your Account", - "nav": { - "overview": "Overview", - "orders": "Orders", - "returns": "Returns", - "messages": "Messages ({num_new_messages})", - "wishlists": "Wish Lists ({num_wishlists})", - "recently_viewed": "Recently Viewed", - "settings": "Account Settings", - "addresses": "Addresses", - "payment_methods": "Payment Methods" - }, - "mobile_nav": { - "messages": "Messages", - "wishlists": "Wish Lists" - } - } + "account": { + "breadcrumb": "Your Account", + "nav": { + "overview": "Overview", + "orders": "Orders", + "messages": "Messages ({num_new_messages})" + } + } } ``` -French translation generated with go-json-translate + +French (Translated): ```json { - "account": { - "breadcrumb": "Votre compte", - "nav": { - "overview": "Vue d'ensemble", - "orders": "Commandes", - "returns": "Renvoyer à", - "messages": "Messages ({num_new_messages})", - "wishlists": "Listes de souhaits ({num_wishlists})", - "recently_viewed": "Récemment consultés", - "addresses": "Adresses", - "settings": "Paramètres du compte", - "payment_methods": "Méthodes de paiement" - }, - "mobile_nav": { - "messages": "Messages", - "wishlists": "Listes de souhaits" - } - } + "account": { + "breadcrumb": "Votre compte", + "nav": { + "overview": "Vue d'ensemble", + "orders": "Commandes", + "messages": "Messages ({num_new_messages})" + } + } } ``` -## Features +## Installation -- Translate **any** standard json file on the spot, leveraging deepL's free API. -- Works well with json files containing **strings, numbers and booleans** -- Supports **nested json files**, without any limit -- Uses a local database as a **translations cache** in order to increase speed and not to request twice the same translations from deepL. This means that once you've translated a file, you can translate it again with the same parameters and not query deepL at all. -- Supports **variables** in the translated text. For example, `hello, {name}` won't be translated to `bonjour, {prénom}` but to `bonjour, {name}` -Available enclosure tags are: `{}, #{} and []`. It's very easy to add new ones. +### Prerequisites +- Go 1.17 or higher +- DeepL API key -#### This tool uses [DeepL free API](https://www.deepl.com/pro#developer). Their free plan includes: +### Install from Source -- Access to all features -- Access to the DeepL REST API -- 500,000 character limit / month -- 1,000 glossaries (for specific languages) - -> On average, text contains **between 5 and 6.5 characters per word** including spaces and punctuation. -charactercounter.com +```sh +git clone https://github.com/gmonarque/go-json-translate +cd go-json-translate +go mod download +go build +``` -Ok, so 500,000 / 6.5 = 76923. We could estimate that we can translate 70k words / month with the free tier. I've actually never hit the limit myself, so kudos to DeepL for a developer plan that actually lets you do stuff :) +## Configuration + +Before using go-json-translate, configure the `config.ini` file: + +```ini +DEEPL_API_ENDPOINT = https://api-free.deepl.com/v2/translate +DEEPL_API_KEY = +``` + +## Usage + +```sh +./go-json-translate -source_path= -output_path= -source_lang= -target_lang= [-ignored_fields=] +``` + +### Options + +- `-source_path`: Path of the source JSON file(s) +- `-output_path`: Path for the output file(s) +- `-source_lang`: Current language of the file (use "autodetect" to let DeepL guess) +- `-target_lang`: Language to translate the file into +- `-ignored_fields`: (Optional) Fields to ignore, separated by semicolons + +### Example + +```sh +./go-json-translate -source_path=folder/*.json -output_path=output/*.json -source_lang=fr -target_lang=en +``` -## Limitations -- This tool depends on DeepL keeping their free tier API usage limit high -- There is no support yet for json arrays, the only supported types are strings, numbers and booleans -- The json source file is entirely read before translation. This means that if you have a **really** huge file to translate, there may be some instability depending on your hardware. But don't worry, thanks to the local translation cache, everything translated with DeepL won't be translated twice. -- The translated json file won't be in the order of the source file. This is not a problem at all, but just so you know. ## Available Languages ### Source Languages @@ -105,48 +113,33 @@ BG, CS, DA, DE, EL, EN, ES, ET, FI, FR, HU, ID, IT, JA, KO, LT, LV, NB, NL, PL, ### Target Languages AR, BG, CS, DA, DE, EL, EN-GB, EN-US, ES, ET, FI, FR, HU, ID, IT, JA, KO, LT, LV, NB, NL, PL, PT-BR, PT-PT, RO, RU, SK, SL, SV, TR, UK, ZH, ZH-HANS, ZH-HANT -Note: Not all source languages can be used as target languages. The target languages list includes some specific variants (e.g., EN-GB, EN-US, PT-BR, PT-PT, ZH-HANS, ZH-HANT) that are not available as source languages. +Note: Not all source languages can be used as target languages. For the most up-to-date list, refer to [DeepL's API documentation](https://www.deepl.com/docs-api/translating-text/request/). -For the most up-to-date list of available languages, please refer to [DeepL's API documentation](https://www.deepl.com/docs-api/translating-text/request/). +## Limitations -## Installation and Usage +- Depends on DeepL's free tier API usage limits +- No support for JSON arrays +- Large files may cause instability depending on hardware +- Output JSON order may differ from the source file -### Install from Sources -```sh -git clone https://github.com/gmonarque/go-json-translate -cd go-json-translate && go mod download && go build -``` +## Contributing -### Configuration -Before using go-json-translate, you need to configure the `config.ini` file: +Contributions are welcome! Please feel free to submit a Pull Request. -```ini -DEEPL_API_ENDPOINT = https://api-free.deepl.com/v2/translate -DEEPL_API_KEY = -``` +## Community Translations -### Usage -```sh -Usage: ./go-json-translate -source_path= -output_path= -source_lang= -target_lang= [-ignored_fields=] - -Options: - -source_path string - Path of the source .json file(s) - -output_path string - Path for the output file(s) - -source_lang string - Current language of the file. Use "autodetect" to let DeepL guess the language. (default "autodetect") - -target_lang string - Language the file will be translated to - -ignored_fields string - Ignored fields separated by semicolon (optional) - -Example: - ./go-json-translate -source_path=folder/*.json -output_path=output/*.json -source_lang=fr -target_lang=en -``` -### Contribute & issues -Don't hesitate to contribute to this project in any way you want. Just use gofmt and feel my vibe. -If you have any issues with this, please open an issue, I'll happily respond. +If you've translated something that could be useful to others, please submit a merge request with your translated file in the `community-translated-files` folder. +## License -**If you have translated something and you think it could be useful to somebody else, please do a merge request of your translated file (check the `community-translated-files` folder)** +This project is licensed under the [MIT License](LICENSE). + +## Contact + +For any questions or issues, please [open an issue](https://github.com/gmonarque/go-json-translate/issues) on GitHub. + +--- + +

+ Personal Website +