https://github.com/reececomo/transl8r
A simple utility for managing JSON language files in projects
https://github.com/reececomo/transl8r
i18n l10n language multi-lingual translation
Last synced: 3 months ago
JSON representation
A simple utility for managing JSON language files in projects
- Host: GitHub
- URL: https://github.com/reececomo/transl8r
- Owner: reececomo
- Created: 2021-02-21T17:20:14.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2021-04-13T05:56:10.000Z (about 4 years ago)
- Last Synced: 2025-01-22T03:42:27.604Z (5 months ago)
- Topics: i18n, l10n, language, multi-lingual, translation
- Language: TypeScript
- Homepage:
- Size: 142 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Transl8r ✍️
**역자** - **译者** - **μεταφράστης** - **ਅਨੁਵਾਦਕ** - **tercüman** - **thông dịch viên** - **مترجم**
A simple utility for managing JSON language files in projects.
- [x] Add/remove keys to multiple languages at once.
- [x] Automatically provide fallback translations (provided by Google Translate).
- [x] Perform basic sanity checking.
- [x] Sort translation files.
- [x] Validate translation files.
- [x] Export TODO language translations as CSV.
- [x] Import CSV language files.
## Install
- Install the package.
- Create a `.transl8r.yml` configuration in your project root.
- (Optional) Set up your [Google Translate Credentials](https://cloud.google.com/docs/authentication/getting-started) (required for `--add`, `--alt` and `--backfill` commands)
### Example
#### `.transl8r.yml`
```yml
group: example
languages:
base: en
other: ['fr', 'de']
namespaces:
target: base.generated
other: ['legal', 'base']
path: '/resources/lang/{{lang}}/{{namespace}}.json'
validation:
mismatchedPlaceholders:
- error.validation.required
```
## Basic Usage
Get a full list of commands like this:
```bash
yarn transl8r --help
```
## Usage
### Housekeeping
#### `--lint` Lint translation files
Lets you know if there's any issues that may affect the translation files.
```bash
Failed to validate, there were 2 errors:
fr: "error.validation.required" has mismatched markup tags:
- <0>,0> vs
fr: "error.validation.required" has mismatched placeholders:
- {{label}} vs
```
> You may use the YAML file to silence warnings for mismatched placeholders.
#### `--clean` Clean unreachable translations
Remove dead keys from generated files where they exist in the professional translation file.
```bash
yarn transl8r --clean
fr: Up to date ✓
de: Purged 14 unreachable key(s).
✨ Done in 0.53s.
```
#### `--sort` Sort translation files
Sort all the language files by key.
### Managing translations
#### `--add` (or `-a`) Add single key
Adds a new generated key to all language files, including the base language.
```bash
yarn transl8r -a button.dismiss.label
>> value: Dismiss
el: Απολύω
→ Fire
it: Respingere
→ Reject
...
✨ Done in 3.87s.
```
#### `--alt` Lost in translation?
Use alternative copy for the translations, without affecting the base (English) translation.
> For example: "Dismiss" has many meanings in English, such as "to treat as unworthy of serious consideration".
> A phrase like "Close prompt" may translate better.
```
yarn transl8r --alt button.dismissPrompt.label -l ar it zh-tw
>> translateAs: Close prompt
ar: موجه إغلاق
→ Close prompt
it: Chiudi prompt
→ Close prompt
zh-tw: 關閉提示
→ Turn off the prompt
✨ Done in 1.46s.
```
#### `--remove` Remove a single key
When you've added a key you no longer want:
```
yarn transl8r --remove button.legacy.close
```
#### `--backfill` Backfill missing translations
**Note:** This command currently does not reverse translations for sanity checking.
```bash
yarn transl8r --backfill
# ...or specific languages only
yarn transl8r --backfill -l fr de
```
### CSV import/export
#### `--exportTodo` Export strings that need translating
Exports a .ZIP archive containing CSV files ready to translate.
```
my-app-todo-2022-07-23.zip/
my-app.es.csv
my-app.fr.csv
my-app.zh-cn.csv
```
##### Format example
| contextKey | en | fr |
| ------------- | ------------- | ----- |
| btn.continue | Continue | |
| btn.cancel | Cancel | |
| btn.dismiss | Dismiss | |
#### `--importCsv` Import strings that need translating
Exports a .ZIP archive containing CSV files ready to translate.
#### Accepts these formats:
##### Translated base format
| contextKey | en | fr |
| ------------- | ------------- | --------- |
| btn.continue | Continue | Continuez |
| btn.cancel | Cancel | Annuler |
| btn.dismiss | Dismiss | Rejeter |
##### Translations only format
| contextKey | fr |
| ------------- | --------- |
| btn.continue | Continuez |
| btn.cancel | Annuler |
| btn.dismiss | Rejeter |
### Options
- `-l` - Supply list of language codes to fetch (space seperated: `-l fr de es`)
- `-p` - Path to match the language files on (use `{{lang}}` and `{{namespace}}` placeholders)
- `-b` - Base language to translate from (default: `en`)
- `-n` - The destination namespace (default: `base.generated`)
Say for example, you add a new translation for Catalyst into French, and you want to backfill it to English and Chinese (Traditional).
```bash
yarn transl8r --backfill -b fr -l en zh-TW
```