@l10nmonster/cli

Command-line interface for L10n Monster v3 - continuous localization for the rest of us.

Installation

From npm

npm install -g @l10nmonster/cli

From source

git clone [email protected]:l10nmonster/l10nmonster.git
cd l10nmonster
npm install
npm run build
npm link --global @l10nmonster/cli

Getting Started

Create a configuration file l10nmonster.config.mjs at your project root, then use the CLI commands to manage translations.

Basic Configuration

// l10nmonster.config.mjs
import { FsSource, FsTarget } from '@l10nmonster/core';

export default {
  channels: [{
    source: new FsSource({ globs: ['src/**/*.json'] }),
    target: new FsTarget({ 
      targetPath: (lang, resourceId) => resourceId.replace('/en/', `/${lang}/`) 
    })
  }],
  
  providers: [{
    id: 'internal',
    provider: 'InternalLeverage'
  }]
};

v3 Commands

Core Operations

# Analyze source content
l10n analyze

Analyzes your sources and reports insights like repeated content, quality metrics, and translation opportunities.

# Capture source content snapshot
l10n source snap

Creates a snapshot of your source content for translation workflows.

# Generate translations
l10n translate

Processes translation requests through configured providers and generates translated resources.

# Update operations and target resources
l10n ops update

Updates target resources with latest translations and manages operation lifecycle.

Translation Memory

# Synchronize TM with providers
l10n tm syncup

Uploads completed translations to translation memory stores.

# Download translations from TM
l10n tm syncdown  

Downloads latest translations from translation memory to local stores.

# Export TM data
l10n tm export

Exports translation memory data for backup or external processing.

Source Management

# List source content
l10n source list

Lists all detected source content with metadata and statistics.

# Query specific content
l10n source query --filter "*.json"

Queries source content with filters and search criteria.

# Show untranslated content
l10n source untranslated --target es

Shows untranslated content for specific target languages.

Operations Management

# View operation details
l10n ops view

Displays detailed information about current operations and their status.

# Manage jobs
l10n ops jobs --status pending

Lists and manages translation jobs by status or other criteria.

# Provider operations
l10n ops providers

Shows configured providers and their current status.

# Delete operations
l10n ops delete --job-id abc123

Removes specific operations or jobs from the system.

Legacy Commands (v2 compatibility)

# Legacy push operation
l10n push

Deprecated: Use l10n translate and l10n ops update instead.

# Legacy pull operation  
l10n pull

Deprecated: Use l10n tm syncdown and l10n ops update instead.

# Legacy status command
l10n status

Deprecated: Use l10n analyze for detailed insights.

Working Files

L10n Monster v3 maintains its working files in a l10nmonster/ directory at the root of the project:

• TM stores: l10nmonster/tm/ - Translation memory data
• Operations: l10nmonster/ops/ - Job and task management
• Snapshots: l10nmonster/snap/ - Source content snapshots
• Providers: l10nmonster/providers/ - Provider-specific data

Working files are source-control friendly (JSON/JSONL files with consistent formatting) and should be checked in for team collaboration.

Advanced CLI Options

The CLI supports additional options to control behavior:

• -c, --config <path>: Specify custom configuration file path
• -v, --verbose: Output additional debug information
• --dry-run: Preview operations without making changes
• --parallel <number>: Set parallelism level for operations
• --filter <pattern>: Apply filters to operations

Example Usage

# Run with custom config and high verbosity
l10n translate -c ./custom.config.mjs -v

# Preview operations without executing
l10n ops update --dry-run

# Parallel translation processing
l10n translate --parallel 4

# Filter specific content
l10n source snap --filter "components/**/*.json"

v3 Configuration

ESM Configuration Format

v3 uses ESM-based configuration files (l10nmonster.config.mjs):

import { FsSource, FsTarget } from '@l10nmonster/core';
import { GptAgent } from '@l10nmonster/helpers-openai';

export default {
  // Source and target channels
  channels: [{
    source: new FsSource({ 
      globs: ['src/**/*.json'],
      targetLangs: ['es', 'fr', 'de']
    }),
    target: new FsTarget({ 
      targetPath: (lang, id) => id.replace('/en/', `/${lang}/`) 
    })
  }],

  // Translation providers
  providers: [{
    id: 'ai-translator',
    provider: new GptAgent({ model: 'gpt-4' })
  }, {
    id: 'internal',
    provider: 'InternalLeverage'
  }],

  // Content type definitions
  contentTypes: [{
    name: 'json',
    resourceFilter: 'i18next'
  }],

  // Storage configuration
  stores: {
    tm: 'BaseJsonlTmStore',
    ops: 'FsOpsStore'
  }
};

Multi-Channel Configuration

export default {
  channels: [
    {
      // Web app content
      source: new FsSource({ globs: ['web/src/**/*.json'] }),
      target: new FsTarget({ targetPath: (lang, id) => id.replace('/src/', `/dist/${lang}/`) })
    },
    {
      // Mobile app content  
      source: new FsSource({ globs: ['mobile/strings/**/*.xml'] }),
      target: new FsTarget({ targetPath: (lang, id) => id.replace('/strings/', `/strings-${lang}/`) })
    }
  ]
};

Provider Chains

export default {
  providers: [
    { id: 'leverage', provider: 'InternalLeverage' },
    { id: 'repetitions', provider: 'Repetition' },
    { id: 'ai', provider: new GptAgent({ model: 'gpt-4' }) },
    { id: 'fallback', provider: 'Invisicode' }
  ]
};

Error Handling

The CLI provides comprehensive error handling with actionable messages:

# Configuration errors
Error: Configuration file not found: l10nmonster.config.mjs
Tip: Run 'l10n init' to create a basic configuration

# Provider errors  
Error: OpenAI API key not configured
Tip: Set OPENAI_API_KEY environment variable or configure apiKey in provider options

# Operation errors
Error: Translation job failed for provider 'gpt-4'
Tip: Check provider configuration and API limits

Performance Optimization

Parallel Processing

# Enable parallel operations
l10n translate --parallel 4

# Provider-specific parallelism
l10n ops update --provider-parallel 2

Filtering and Batching

# Process specific file patterns
l10n translate --filter "*.json"

# Batch operations by language
l10n translate --batch-by-language

# Limit operation scope
l10n source snap --since "2024-01-01"

Integration Examples

CI/CD Pipeline

# GitHub Actions example
name: Localization
on: [push, pull_request]

jobs:
  l10n:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm install -g @l10nmonster/cli
      - run: l10n analyze
      - run: l10n translate --dry-run

NPM Scripts

{
  "scripts": {
    "l10n:analyze": "l10n analyze",
    "l10n:translate": "l10n translate",
    "l10n:update": "l10n ops update",
    "l10n:sync": "l10n tm syncup && l10n tm syncdown"
  }
}

Troubleshooting

Common Issues

1. Configuration not found

   # Ensure config file exists and has correct name
   ls l10nmonster.config.mjs

2. Module import errors

   # Verify Node.js version (requires >= 22.11.0)
   node --version

3. Provider authentication

   # Check environment variables
   echo $OPENAI_API_KEY

4. Performance issues

   # Enable debug logging
   l10n translate -v

Migration from v2

Configuration Updates

1. Rename config file: l10nmonster.cjs → l10nmonster.config.mjs
2. Update imports: Use ESM import syntax
3. Update providers: Many providers have new names and APIs
4. Update commands: Some command names have changed

Command Mapping

| v2 Command | v3 Equivalent | |------------|---------------| | l10n push | l10n translate && l10n ops update | | l10n pull | l10n tm syncdown && l10n ops update | | l10n status | l10n analyze | | l10n grandfather | Provider-based (configured in config) | | l10n leverage | Provider-based (configured in config) |

For detailed migration guidance, see the v3 Migration Guide.

Help and Support

# Get general help
l10n help

# Get command-specific help
l10n help translate
l10n help ops
l10n help source

# Get provider information
l10n ops providers --info

For more detailed documentation, see:

• Main Documentation
• Architecture Guide
• Core Package Documentation