i18nflow-cli

AI-powered locale management for JSON-based i18n projects.

✨ What this CLI does

i18nflow helps you create and maintain translation files from a single source JSON file.

It can:

• initialize a locale project from a base language
• generate new locale files like es.json, fr.json, or pt.json
• detect missing keys against the source locale
• translate only the missing values and merge them into the target locale
• compare a locale with the base file
• list and validate project health before publishing

🚀 Installation

Global install

npm install -g @aelith-dev/i18nflow-cli

Local project usage

npx @aelith-dev/i18nflow-cli --help

🔑 Environment setup

Create a .env file in your project root or export the key in your shell:

GEMINI_API_KEY=your_gemini_key
# or
GROQ_API_KEY=your_groq_key

You only need one provider to work with the CLI.

🧩 Recommended project structure

my-app/
├── locales/
│   ├── en.json
│   ├── es.json
│   └── fr.json
├── i18nflow.config.json
├── .env
└── src/

Example base file:

{
  "header": {
    "title": "Welcome",
    "cta": "Get started"
  },
  "profile": {
    "logout": "Log out"
  }
}

🛠️ Command overview

i18nflow init

Creates a locale configuration and a source locale file.

i18nflow init

You can also pass values directly:

i18nflow init --source en --dir ./locales --targets es fr de

This creates:

• locales/en.json
• i18nflow.config.json

i18nflow add <locale>

Generates a new locale JSON file using the source file as the base.

i18nflow add es

This creates locales/es.json and translates all values from the source locale.

i18nflow sync [locale]

Syncs missing keys across a target locale or all configured locales.

i18nflow sync
# or
i18nflow sync fr

i18nflow diff <locale>

Shows missing or different keys between the source file and a target locale.

i18nflow diff es

i18nflow list

Lists configured locales and available JSON files.

i18nflow list

i18nflow status

Shows the sync health of each target locale.

i18nflow status

i18nflow doctor

Checks for missing files and missing API keys.

i18nflow doctor

i18nflow remove <locale>

Removes a target locale file and deletes it from config.

i18nflow remove fr

📄 Configuration file

The CLI stores configuration as JSON by default:

{
  "source": "en",
  "localesDir": "./locales",
  "targets": ["es", "fr", "de"]
}

This file is saved as i18nflow.config.json in your project root.

🔄 Typical workflow

# 1. initialize the project
npx i18nflow init --source en --dir ./locales --targets es fr

# 2. edit the base locale file
# locales/en.json

# 3. generate a new locale
npx i18nflow add es

# 4. sync missing keys after content changes
npx i18nflow sync

# 5. check differences
npx i18nflow diff es

🛡️ License

MIT © Darieth Jasso

Part of the Aelith Studio ecosystem.