flutter_i18n_translator 0.1.1+2

A Flutter/Dart CLI tool that detects missing keys in JSON localization files, auto-translates them, and can regenerate Dart i18n helpers.

Perfect 👍 Here’s the updated README.md with a clear note about requiring i18n_json when using --autoGenerate:

# flutter_i18n_translator

[![pub package](https://img.shields.io/pub/v/flutter_i18n_translator.svg)](https://pub.dev/packages/flutter_i18n_translator)

A CLI tool to automatically translate missing keys in JSON localization files for Flutter/Dart
projects.  
It uses [translator](https://pub.dev/packages/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`](https://pub.dev/packages/i18n_json).

---

## 📦 Installation

Activate globally from [pub.dev](https://pub.dev/packages/flutter_i18n_translator):

```bash
dart pub global activate flutter_i18n_translator

Or use locally in a project:

dev_dependencies:
  flutter_i18n_translator: ^0.1.1+2

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
--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

---

🛠 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

---

📄 License

MIT License © 2025 Mazen El-Gayar