Skip to content

Commit

Permalink
docs: update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@gmonarque
gmonarque committed Oct 19, 2024
1 parent de4f54c commit 7b88b37
Showing 1 changed file with 107 additions and 114 deletions.
221 changes: 107 additions & 114 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,102 +1,110 @@
<h1 align="center">
<img
width="300"
alt="go-json-translate"
src="images/go-json-translate-logo.svg">
</h1>

<h3 align="center">
Translate json language files / i18n locales on the spot!
</h3>
# go-json-translate

<p align="center">
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!
<img width="300" alt="go-json-translate" src="images/go-json-translate-logo.svg">
</p>
<p align="center">

[![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)

<strong>
<a href="https://gmsec.fr/">Personnal website</a>
</strong>
<p align="center">
<strong>Translate JSON language files / i18n locales on the spot!</strong>
</p>

<p align="center">
<a href="https://github.com/gmonarque/go-json-translate/issues">
<img src="https://img.shields.io/github/issues/gmonarque/go-json-translate" alt="GitHub issues">
</a>
<a href="https://github.com/gmonarque/go-json-translate/blob/main/LICENSE">
<img src="https://img.shields.io/github/license/gmonarque/go-json-translate" alt="GitHub license">
</a>
</p>

## 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 = <your_api_key>
```

## Usage

```sh
./go-json-translate -source_path=<path> -output_path=<path> -source_lang=<lang> -target_lang=<lang> [-ignored_fields=<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
Expand All @@ -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 = <your_api_key>
```
## Community Translations

### Usage
```sh
Usage: ./go-json-translate -source_path=<path> -output_path=<path> -source_lang=<lang> -target_lang=<lang> [-ignored_fields=<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.

---

<p align="center">
<a href="https://gmsec.fr/">Personal Website</a>
</p>

0 comments on commit 7b88b37

Please sign in to comment.