multilingual-cli

v2.1.1

Published

2 months ago

Multilingual - Automated i18n with FREE translation options. 6 translation services (4 free, 2 paid), 37 languages, multiple export formats, watch mode, translation memory.

Downloads

146

🌐 Multilingual CLI v2.0

Automated i18n with FREE translation options — 15+ translation methods (12 free!), 37 languages, offline mode, multiple export formats, and more.

✨ What's New in v2.0

🆓 12 Free Translation Methods — No billing required!
📂 Offline Translation — Built-in dictionaries, no internet needed
🎨 Creative Modes — Pig Latin, Emoji, L33t, Morse Code, NATO phonetic
📊 Statistics & Cost Estimation — Plan before you translate
📦 Multiple Export Formats — XLIFF, PO/gettext, CSV, Android, iOS, ARB
👀 Watch Mode — Auto-translate during development
🧪 Pseudo-localization — Test UI with fake translations
💾 Translation Memory — Reuse translations with fuzzy matching
🔒 Enhanced Security — API keys never exposed in logs

🚀 Quick Start

# Install globally
npm install -g multilingual-cli

# Initialize in your project
multilingual init

# Or use directly with npx
npx multilingual-cli init

📋 Translation Services

🆓 FREE Online (No Billing Required)

| Service | Description | Limit | |---------|-------------|-------| | MyMemory | Crowd-sourced + machine translation (recommended) | 10k chars/day (100k with email) | | LibreTranslate | Open source, self-hostable | Unlimited | | Lingva | Privacy-focused (may be blocked by Cloudflare) | Unlimited |

📂 Offline (No Internet Required)

| Service | Description | Use Case | |---------|-------------|----------| | Dictionary | Built-in dictionaries for 10 languages | Quick translations, no API | | Local | Use your own JSON translation files | Custom terminology |

🎨 Creative & Testing (Instant)

| Service | Description | Example | |---------|-------------|---------| | Pseudo | Fake translations with accents | [Ḥḛŀŀő Ẇőřŀḓ~~~] | | Piglatin | Classic word game | ellohay orldway | | Emoji | Words → emojis | 👋 🌍 | | Leet | L33t sp34k | h3ll0 w0rld | | Reverse | Reversed text | dlrow olleh | | Mirror | Unicode mirror chars | ꓭ⅃ꓤOW O⅃⅃ƎH | | Morse | Morse code | .... . .-.. .-.. --- | | NATO | NATO phonetic alphabet | Hotel Echo Lima Lima Oscar | | Uppercase | ALL CAPS | HELLO WORLD |

💳 Paid (Free Tier Available)

| Service | Description | Free Tier | |---------|-------------|-----------| | DeepL | High quality neural translation | 500k chars/month | | Google | Wide language support | 500k chars/month |

# Use free Lingva (recommended, no API key needed!)
multilingual translate-file -s en.json -o ./locales --service lingva

# Use offline dictionary (no internet required!)
multilingual translate-file -s en.json -o ./locales --service dictionary

# Fun: translate to Pig Latin
multilingual translate-file -s en.json -o ./locales --service piglatin

# View all service options
multilingual services

🛠️ CLI Commands

Core Commands

multilingual init              # Interactive setup wizard
multilingual run               # Scan & translate project
multilingual scan              # Scan only, show strings
multilingual translate-file    # Translate existing JSON file

Export & Import

# Export to XLIFF for translation tools
multilingual export -i en.json -o translations.xliff -f xliff

# Import translated XLIFF
multilingual import -i translated.xliff -o fr.json

# Supported formats: xliff, xliff2, po, csv, android, ios, arb

Development Tools

multilingual watch             # Auto-translate on file changes
multilingual pseudo -s en.json # Generate pseudo-translations
multilingual stats             # View statistics & cost estimates

Configuration

multilingual config --show     # View current config
multilingual config --edit     # Interactive config editor
multilingual config --set key=value
multilingual services          # List all translation services
multilingual languages         # List all 37 supported languages

🌍 Supported Languages (37)

| | | | | |---|---|---|---| | 🇺🇸 English | 🇪🇸 Spanish | 🇫🇷 French | 🇩🇪 German | | 🇮🇹 Italian | 🇵🇹 Portuguese | 🇧🇷 Portuguese (BR) | 🇷🇺 Russian | | 🇨🇳 Chinese (Simplified) | 🇹🇼 Chinese (Traditional) | 🇯🇵 Japanese | 🇰🇷 Korean | | 🇸🇦 Arabic (RTL) | 🇮🇳 Hindi | 🇳🇱 Dutch | 🇵🇱 Polish | | 🇸🇪 Swedish | 🇩🇰 Danish | 🇫🇮 Finnish | 🇳🇴 Norwegian | | 🇹🇷 Turkish | 🇨🇿 Czech | 🇬🇷 Greek | 🇮🇱 Hebrew (RTL) | | 🇭🇺 Hungarian | 🇮🇩 Indonesian | 🇲🇾 Malay | 🇹🇭 Thai | | 🇻🇳 Vietnamese | 🇺🇦 Ukrainian | 🇧🇬 Bulgarian | 🇷🇴 Romanian | | 🇸🇰 Slovak | 🇸🇮 Slovenian | 🇪🇪 Estonian | 🇱🇻 Latvian | | 🇱🇹 Lithuanian | | | |

📦 Export Formats

Supported Formats

| Format | Extension | Use Case | |--------|-----------|----------| | JSON | .json | Web apps, Node.js | | XLIFF 1.2 | .xliff | Translation tools (SDL, Trados) | | XLIFF 2.0 | .xliff | Modern CAT tools | | PO/gettext | .po | Linux, WordPress, Python | | CSV | .csv | Spreadsheets, bulk editing | | Android | strings.xml | Android apps | | iOS | .strings | iOS/macOS apps | | ARB | .arb | Flutter apps |

# Convert JSON to XLIFF for professional translators
multilingual export -i en.json -o translations.xliff -f xliff

# Import back from translated XLIFF
multilingual import -i es.xliff -o es.json

🧪 Pseudo-localization

Test your UI's i18n readiness with fake translations:

# Generate pseudo-translations
multilingual pseudo -s en.json -o pseudo.json

Before: "Hello World" After: "[Ḥḛŀŀő Ẇőřŀḓ~~~]"

This helps you:

✅ Find hardcoded strings
✅ Test text expansion (~30% longer)
✅ Verify special character support
✅ Identify concatenated strings

📊 Statistics & Cost Estimation

multilingual stats --report

╔══════════════════════════════════════════════════════════════╗
║              Translation Statistics Report                    ║
╠══════════════════════════════════════════════════════════════╣

📊 SUMMARY
──────────────────────────────────────────────────────────────
  Total strings:    245
  Total words:      1,847
  Total characters: 12,456
  Overall coverage: 78.3%

🌍 LANGUAGE COVERAGE
──────────────────────────────────────────────────────────────
  ✅ Spanish              [████████████████████] 100.0%
  🔄 French               [██████████████░░░░░░] 72.3%
  ⏳ German               [████░░░░░░░░░░░░░░░░] 23.1%

💰 COST ESTIMATES
──────────────────────────────────────────────────────────────
  DeepL Free tier: ~0.4 months of quota
  Google Free tier: ~0.4 months of quota
  ✅ Within free tier limits for both services

🔄 GitHub Actions Automation

multilingual github --setup

Automatically translate on every push:

# .github/workflows/translate.yml
name: Auto-translate
on:
  push:
    paths:
      - 'src/**'
      - 'locales/en.json'

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install -g multilingual-cli
      - run: multilingual run --auto
        env:
          TRANSLATION_API_KEY: ${{ secrets.TRANSLATION_API_KEY }}
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: 'chore: update translations'

💻 Programmatic Usage

import Multilingual, { 
  TranslationManager, 
  calculateStats,
  exportToFile,
  XLIFFFormat 
} from 'multilingual-cli';

// Basic usage
const ml = new Multilingual({
  config: {
    sourceLanguage: 'en',
    targetLanguages: ['es', 'fr', 'de'],
    translationService: 'none', // Use free service instead
  }
});

// Use free translation service
const manager = new TranslationManager();
manager.setExtendedService('libretranslate'); // No API key needed!

const result = await manager.translate('Hello World', 'es', 'en');
console.log(result.text); // "Hola Mundo"

// Pseudo-translation for testing
const pseudo = manager.generatePseudoTranslation('Hello World');
console.log(pseudo); // "[Ḥḛŀŀő Ẇőřŀḓ~~~]"

// Export to XLIFF
const doc = {
  sourceLanguage: 'en',
  targetLanguage: 'es',
  units: [
    { key: 'greeting', source: 'Hello', target: 'Hola' },
    { key: 'farewell', source: 'Goodbye', target: 'Adiós' },
  ]
};
const xliff = XLIFFFormat.export(doc);

🔒 Security

API keys are never exposed:

✅ Keys masked in logs (AIza****...****V8Isd3A)
✅ Uses environment variables
✅ .env.example template included
✅ Keys never written to translation files
✅ Error messages sanitized

# Use environment variable
export TRANSLATION_API_KEY="your-key-here"
multilingual run --auto

📁 Project Structure

your-project/
├── locales/
│   ├── en.json        # Source language
│   ├── es.json        # Auto-generated
│   ├── fr.json        # Auto-generated
│   └── ...
├── .multilingual/
│   ├── translation-memory.json  # Reusable translations
│   └── reports/                 # Statistics reports
├── multilingual.config.json     # Configuration
└── .env                         # API keys (git-ignored)

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines first.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

MIT License — see LICENSE for details.

Attribution Required: Generated translation files must retain the multilingual-cli attribution comments.

🔗 Links

npm: npmjs.com/package/multilingual-cli
GitHub: github.com/NagusameCS/Multilingual
Documentation: NagusameCS.github.io/Multilingual