Usage

Initialize JSON DeepL CLI

To get started with JSON DeepL CLI, you need to initialize it in your project. This will create a configuration file that stores your settings and preferences.

npx jsondeepl@latest

Or if you have installed JSON DeepL CLI globally or as a dependency, you can run below command at the root of your project:

jsondeepl

First time running the command on your project will create a jsondeepl directory in your project root along with a config.json file. This file contains the default configuration settings for JSON DeepL CLI.

Configuration File

The configuration file is a JSON file that contains the settings for JSON DeepL CLI. You can modify this file to customize the behavior of the CLI. See config options for more details.

{
  "source": "en", // add your source (default) language here
  "target": ["de", "zh"], // add your target languages here
  "langDir": "./i18n/locales", // change this to your locales directory
  "options": {
    "autoMerge": true,
    "prompt": true
  }
}

Set Your API Key

JSONDEEPL_API_KEY="your_deepl_api_key_here"

Run JSON DeepL CLI

Once you have modified the configuration file, you can run the CLI command again to translate your JSON files.

npx jsondeepl@latest

jsondeepl

How It Works

Updating Translations

You can rerun the CLI command whenever you make changes to your source JSON file. The CLI will detect the changes and update the translations accordingly. it will do the following:

• Translate only the new or modified keys in the source JSON file.
• Keep the existing translations for the unchanged keys and automatically merge them.
• Remove any keys that have been deleted from the source JSON file.

this way, your translations will always be synced with your source JSON file without losing any existing translations.

Automatic New Language Detection

The CLI automatically detects when you add new target languages to your configuration and handles them intelligently:

• Existing languages: Only translate changed/new keys (incremental updates)
• New languages: Translate the entire source file (full translation)

Detection Logic

1. When you run the CLI, it checks each target language in your config
2. For each language, it looks for the corresponding .json file in your langDir
3. If the file doesn't exist → new language → translates all keys
4. If the file exists → existing language → translates only changed keys (compared to lock file)

Example Scenario

Initial Setup:

// jsondeepl/config.json
{
  "source": "en",
  "target": ["fr", "es"],
  "langDir": "./i18n/locales"
}

Files:

i18n/locales/
  ├── en.json       (100 keys)
  ├── fr.json       (100 keys - fully translated)
  └── es.json       (100 keys - fully translated)

jsondeepl/
  └── en-lock.json  (100 keys)

Adding a New Language

Update config:

{
  "source": "en",
  "target": ["fr", "es", "de"],  // Added "de"
  "langDir": "./i18n/locales"
}

Run the CLI:

jsondeepl

What Happens:

1. ✅ CLI detects de.json doesn't exist
2. 📢 Console output: Detected new target language: de - will translate all keys
3. 🔄 Translation behavior:
   • fr: Only translates if you added/changed keys in en.json (incremental)
   • es: Only translates if you added/changed keys in en.json (incremental)
   • de: Translates all 100 keys from en.json (full translation)

Character Count Example

fr: 0 characters    (no changes in source)
es: 0 characters    (no changes in source)
de: 5000 characters (full translation of all keys)
Total characters to translate: 5000

Benefits

✅ No manual intervention needed - Just add the language code to config
✅ Cost efficient - Only pays for what needs to be translated
✅ Smart detection - Handles mixed scenarios automatically
✅ Works with existing workflow - No breaking changes

Use Cases

1. Adding a Single New Language

// Before: ["en-US", "fr"]
// After:  ["en-US", "fr", "de"]

Result: German gets full translation, French gets incremental updates

2. Adding Multiple New Languages

// Before: ["en", "fr"]
// After:  ["en", "fr", "de", "es", "it"]

Result: German, Spanish, Italian get full translations, French gets incremental updates