flutter_i18n_translator

A CLI tool to automatically translate missing keys in JSON localization files for Flutter/Dart projects.
It uses translator under the hood (Google Translate API).

✨ Features

Detects missing keys in your i18n JSON files.
Translates missing entries using Google Translate.
Supports batching with character limits.
Placeholders ({digit}, {name}, etc.) are preserved during translation.
Configurable via i18nconfig.json.
CLI flags to enable automation & debug logging.
Auto-generate Dart i18n files using i18n_json.
Convert all JSON keys to a specific case (camelCase, PascalCase, snake_case, kebab-case).
Adds a locale setter that automatically calls onLocaleChanged when Locale Changes.
Adds a current static I18n instance for direct access (no context required).
JSON-backed tr("key") lookup — use dynamic keys alongside typed getters (I18n.tr("hello"), "hello".tr()).
Runtime I18nJsonLoader for loading JSON maps directly in Dart code.
Ensures missing WidgetsLocalizations overrides are included.

❤️ Support the Project

If this package saved you development time, please consider supporting the work behind it:

PayPal Donation

👉 https://paypal.me/mazenelgayar

InstaPay

👉 https://ipn.eg/S/mazenel-gayarcib/instapay/0ecfXw Tag: mazenel-gayarcib@instapay

Your support directly motivates further updates, improvements, and new features. Thank you! ❤️🙏

📦 Installation

Activate globally from pub.dev:

dart pub global activate flutter_i18n_translator

Or use locally in a project:

dev_dependencies:
  flutter_i18n_translator: ^0.2.0

Run from project root:

dart run flutter_i18n_translator

⚙️ Configuration

Create an i18nconfig.json in your project root:

{
  "defaultLocale": "en-US",
  "locales": [
    "en-US",
    "ar-EG",
    "fr-FR",
    "es-ES",
    "de-DE",
    "it-IT",
    "ru-RU",
    "ja-JP",
    "ko-KR",
    "pt-PT",
    "hi-IN",
    "tr-TR"
  ],
  "localePath": "i18n",
  "generatedPath": "lib/generated",
  "ltr": [
    "en-US",
    "fr-FR",
    "es-ES",
    "de-DE",
    "it-IT",
    "ru-RU",
    "ja-JP",
    "ko-KR",
    "pt-PT",
    "hi-IN",
    "tr-TR"
  ],
  "rtl": [
    "ar-EG"
  ]
}

defaultLocale: The base locale with full translations.
locales: List of all locales you support.
localePath: Directory where JSON files are stored.
generatedPath: Directory where i18n will generate Dart files.
ltr: Locales that are Left to Right.
rtl: Locales that are Right to Left.

Example structure:

project_root/
  i18n/
    en-US.json
    fr-FR.json
    ar-EG.json
  lib/
    generated/
      i18n.dart
  i18nconfig.json

🚀 Usage

Run the tool from your project root:

flutter_i18n_translator

CLI Options

--batch-limit <number>         Set max characters per translation batch (default: 3000)
--auto-translate               Automatically send translations without confirmation
--auto_apply-translations      Apply translations without user prompt
--autoGenerate                 Automatically run `dart run i18n_json` to regenerate Dart files
--no-autoGenerate              Disable automatic file generation
--show-debug                   Enable debug messages
--no-debug                     Disable debug messages
--addMissingOverrides          Ensure WidgetsLocalizations overrides are added to I18n
--no-addMissingOverrides       Disable adding WidgetsLocalizations overrides to I18n
--key-case <style>             Convert all JSON keys to a specific case (camel, pascal, snake, kebab)
--autoDartFixGeneratedFile     Automatically run 'dart fix --apply' on generated files
--no-autoDartFixGeneratedFile  Disable automatic 'dart fix' after generation
--enhanceGeneratedFile         Enhances the generated I18n Dart file by modifying the locale setter 
                               to call onLocaleChanged interally when changing locale,
                               and adds a static `current` I18n instance so you can access translations
                               without passing a BuildContext.
--no-enhanceGeneratedFile      Disable enhancing the generated I18n file.
--addTrLookup                  Inject JSON-backed tr("key") lookup into generated I18n (default: on)
--no-addTrLookup               Skip injecting tr("key") lookup
--help, -h                     Show this help message

⚠️ Note: To use --autoGenerate, you must add i18n_json to your project:

dev_dependencies:
  i18n_json: ^1.0.0

Examples

Translate with default options:

flutter_i18n_translator

Set a smaller batch limit:

flutter_i18n_translator --batch-limit 1000

Translate & apply automatically:

flutter_i18n_translator --auto-translate --auto_apply-translations

Translate and regenerate Dart i18n file automatically:

flutter_i18n_translator --autoGenerate

Run silently without debug logs:

flutter_i18n_translator --no-debug

Convert all keys to snake_case:

flutter_i18n_translator --key-case snake

🔤 Dynamic key lookup with `tr("key")`

When --enhanceGeneratedFile is enabled (default), the generated I18n class embeds your locale JSON using one key per translation — no duplicate aliases.

Pick the key format at generation time:

Style	Flat key example	Nested `profile.title` example
`dot` (default)	`share_profile_title`	`profile.title`
`camel`	`shareProfileTitle`	`profileTitle`
`snake`	`share_profile_title`	`profile_title`
`kebab`	`share-profile-title`	`profile-title`

Configure via i18nconfig.json:

{
  "flattenKeyStyle": "dot"
}

Or CLI:

flutter_i18n_translator --flatten-key-style camel

Usage:

// Static — uses the active I18n.locale (no BuildContext)
final title = I18n.tr('share_profile_title');   // dot style
final title = I18n.tr('shareProfileTitle');     // camel style

// String extension
final msg = 'downloaded_successfully'.tr();

// Placeholders
final greeting = I18n.tr('greeting', {'name': 'Dr. Smith'});

tr() normalizes your input to the chosen style, so with camel you can pass "profile.title" or "profileTitle".

Disable injection with --no-addTrLookup if you only want typed getters.

Standalone runtime loader

Import the library in your app (not only the CLI):

dependencies:
  flutter_i18n_translator: ^0.2.1

import 'package:flutter_i18n_translator/i18n_loader.dart';

final loader = I18nJsonLoader.fromJsonString(jsonString);
loader.tr('hello');
loader.tr('greeting', args: {'name': 'Mazen'});

This README is already strong 💪 — especially the positioning + monetization section (smart move).

You asked to add steps for VSCode / Cursor without inventing anything — so here’s a clean, README-ready section you can paste directly under the Android Studio section.

⚡ VSCode / Cursor Integration

You can run flutter_i18n_translator directly from VSCode or Cursor using Tasks or a custom keyboard shortcut.

✅ Option 1 — Using VSCode Task (Recommended)

1️⃣ Create a `tasks.json`

Inside your project:

.vscode/tasks.json

If it doesn’t exist:

Press Ctrl + Shift + P
Type: Tasks: Configure Task
Choose: Create tasks.json from template
Select: Others

2️⃣ Add the following configuration

Option A — Using system `dart` (❌ Not recommended with FVM)

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "flutter_i18n_translator",
      "type": "shell",
      "command": "dart run flutter_i18n_translator",
      "group": "build"
    }
  ]
}

Option B — Using FVM (✅ Recommended)

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "flutter_i18n_translator",
      "type": "shell",
      "command": "fvm flutter pub run flutter_i18n_translator",
      "group": "build"
    }
  ]
}

With flags example:

"command": "fvm flutter pub run flutter_i18n_translator --auto-translate --auto_apply-translations"

3️⃣ Run the Task

Press: Ctrl + Shift + B
Or open Command Palette → Run Task
Select: flutter_i18n_translator

🎹 Optional: Bind a Keyboard Shortcut

Open:
- File → Preferences → Keyboard Shortcuts
Search:
```
Run Task
```
Add a shortcut.
Select your flutter_i18n_translator task.

🚀 Cursor Users

Cursor uses the same VSCode task system.

Just create:

.vscode/tasks.json

And use the same configuration shown above.

No additional setup required.

⚡ Android Studio Integration

You can bind the CLI to a keyboard shortcut for faster usage:

Here’s a clean README-ready version, keeping your exact steps, not inventing anything, and only adding both options (dart vs fvm) clearly.

External Tool Setup (Android Studio / IntelliJ)

You can bind the translator CLI to a keyboard shortcut for faster usage.

1. Open External Tools

Go to:

File → Settings → Tools → External Tools

2. Click + to add a new tool

Tool name

Name: flutter_i18n_translator

Option A — Using system `dart` (❌ NOT recommended with FVM)

⚠️ This uses the global Dart SDK. If your project uses FVM, this may fail due to Dart version mismatch.

Program: dart

Arguments:

run flutter_i18n_translator

Or with flags:

run flutter_i18n_translator --auto-translate --auto_apply-translations

Working directory:
```
$ProjectFileDir$
```

Option B — Using FVM (✅ recommended)

✅ This ensures the tool uses the project’s Flutter & Dart version.

Program: fvm

Arguments:

flutter pub run flutter_i18n_translator

Or with flags:

flutter pub run flutter_i18n_translator --auto-translate --auto_apply-translations

Working directory:
```
$ProjectFileDir$
```

3. Save and close

4. Assign a keyboard shortcut

Go to File → Settings → Keymap
Search for your tool name: flutter_i18n_translator
Right-click → Add Keyboard Shortcut
Assign your preferred key combination

5. Done 🎉

You can now run translations directly using your keyboard shortcut inside Android Studio.

🛠 Development

Clone the repo:

git clone https://github.com/MazenxELGayar/flutter_i18n_translator.git
cd flutter_i18n_translator

Run locally:

dart run bin/flutter_i18n_translator.dart --help

flutter_i18n_translator

✨ Features

❤️ Support the Project

PayPal Donation

InstaPay

📦 Installation

⚙️ Configuration

🚀 Usage

CLI Options

Examples

🔤 Dynamic key lookup with `tr("key")`

Standalone runtime loader

⚡ VSCode / Cursor Integration

✅ Option 1 — Using VSCode Task (Recommended)

1️⃣ Create a `tasks.json`

2️⃣ Add the following configuration

Option A — Using system `dart` (❌ Not recommended with FVM)

Option B — Using FVM (✅ Recommended)

3️⃣ Run the Task

🎹 Optional: Bind a Keyboard Shortcut

🚀 Cursor Users

⚡ Android Studio Integration

External Tool Setup (Android Studio / IntelliJ)

1. Open External Tools

2. Click + to add a new tool

Tool name

Option A — Using system `dart` (❌ NOT recommended with FVM)

Option B — Using FVM (✅ recommended)

3. Save and close

4. Assign a keyboard shortcut

5. Done 🎉

🛠 Development

📄 License

Libraries

flutter_i18n_translator package

flutter_i18n_translator

✨ Features

❤️ Support the Project

PayPal Donation

InstaPay

📦 Installation

⚙️ Configuration

🚀 Usage

CLI Options

Examples

🔤 Dynamic key lookup with tr("key")

Standalone runtime loader

⚡ VSCode / Cursor Integration

✅ Option 1 — Using VSCode Task (Recommended)

1️⃣ Create a tasks.json

2️⃣ Add the following configuration

Option A — Using system dart (❌ Not recommended with FVM)

Option B — Using FVM (✅ Recommended)

3️⃣ Run the Task

🎹 Optional: Bind a Keyboard Shortcut

🚀 Cursor Users

⚡ Android Studio Integration

External Tool Setup (Android Studio / IntelliJ)

1. Open External Tools

2. Click + to add a new tool

Tool name

Option A — Using system dart (❌ NOT recommended with FVM)

Option B — Using FVM (✅ recommended)

3. Save and close

4. Assign a keyboard shortcut

5. Done 🎉

🛠 Development

📄 License

Libraries

flutter_i18n_translator package

🔤 Dynamic key lookup with `tr("key")`

1️⃣ Create a `tasks.json`

Option A — Using system `dart` (❌ Not recommended with FVM)

Option A — Using system `dart` (❌ NOT recommended with FVM)