CLI18n

A powerful CLI tool for extracting, managing, and translating internationalization keys in your JavaScript projects.

Features

• 🔍 Extract translation keys from source files using customizable regex patterns
• 🔄 Find duplicate translations across locale files to maintain consistency
• 🗑️ Remove unused translations to keep locale files clean and maintainable
• 🌐 Web interface for exploring and translating locale files
• ⚡ Real-time editing with instant file updates
• 🎯 Filter untranslated keys to focus on missing translations
• 📱 Responsive design that works on desktop and mobile

Installation

Global Installation

npm install -g cli18n

Local Installation

npm install --save-dev cli18n

No Installation (using npx)

npx cli18n extract
npx cli18n duplicates
npx cli18n prune-unused
npx cli18n serve

Configuration

Create a cli18n.json file in your project root:

{
  "regex": "t\\('([^']*)'\\)",
  "outputDir": "locales/{{lang}}.json",
  "languages": ["en", "fr", "es"],
  "glob": "**/*",
  "ignore": ["node_modules/**", "dist/**", "build/**"]
}

Configuration Options

• regex - Regular expression to match translation keys in your source code
• outputDir - Template path for locale files (use {{lang}} placeholder)
• languages - Array of language codes to support
• glob - Glob pattern to specify which files to scan (default: **/*)
• ignore - Array of glob patterns to exclude from scanning (common: node_modules/**, dist/**, build/**)

Usage

Extract Translation Keys

Scan your source files and extract translation keys:

# Global installation
cli18n extract

# Local installation (with npm scripts)
npx cli18n extract

This command will:

• Scan files matching your regex pattern
• Generate/update locale files for each language
• Preserve existing translations

Find Duplicate Translations

Identify duplicate translation values across locales:

# Global installation
cli18n duplicates

# Local installation
npx cli18n duplicates

Remove Unused Translations

Clean up locale files by removing translation keys that are no longer used in your codebase:

# Global installation
cli18n prune-unused

# Local installation
npx cli18n prune-unused

This command will:

• Scan your codebase to find actively used translation keys
• Remove any keys from locale files that aren't referenced in your code
• Preserve the structure and organization of your locale files

Start Web Interface

Launch the translation management web interface:

# Global installation
cli18n serve

# Local installation
npx cli18n serve

Options:

• -p, --port <port> - Port to run the server on (default: 3000)

The web interface provides:

• Visual key explorer - Browse all translation keys in a clean interface
• Locale filtering - Focus on specific languages
• Search functionality - Find keys by text search
• Untranslated filter - Show only missing or incomplete translations
• Inline editing - Click to edit translations directly
• Auto-save - Changes are saved immediately to your locale files

Example Workflow

1. Setup - Create your cli18n.json configuration
2. Extract - Run cli18n extract to scan your code and generate locale files
3. Translate - Use cli18n serve to open the web interface and add translations
4. Maintain - Use cli18n duplicates to find and fix duplicate values
5. Clean up - Use cli18n prune-unused to remove obsolete translation keys

Example Project Structure

my-project/
├── cli18n.json
├── src/
│   ├── components/
│   │   └── App.js          // Contains t('welcome.message')
│   └── pages/
│       └── Home.js         // Contains t('home.title')
└── locales/
    ├── en.json             // Generated locale files
    ├── fr.json
    └── es.json

Web Interface Screenshots

The web interface provides an intuitive way to manage your translations:

• Key Explorer: See all your translation keys organized in a clear table
• Live Editing: Click any translation to edit it inline
• Smart Filtering: Filter by locale, search text, or show only untranslated keys
• Visual Feedback: Untranslated keys are highlighted in red

API

You can also use cli18n programmatically:

const { extractTranslations } = require('cli18n/src/extract');
const { findDuplicateTranslations } = require('cli18n/src/duplicates');
const { pruneUnusedTranslations } = require('cli18n/src/prune-unused');
const { startServer } = require('cli18n/src/serve');

// Extract translations
await extractTranslations();

// Find duplicates
await findDuplicateTranslations();

// Remove unused translations
await pruneUnusedTranslations();

// Start web server
startServer(3000);

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

License

MIT

Sponsor

This project is proudly sponsored by Intuifood 🍽️ IntuiFood is the leading restaurant management application system, for small, medium and large restaurants and bars. It offers features such as reservation management, online ordering, vouchers, website generation, hygiene reports, and, much more.

Made with ❤️ for the international development community