@l10nmonster/cli 1.0.5 → 3.0.0-alpha.10

package/.releaserc.json

@@ -0,0 +1,31 @@
+{
+  "branches": [
+    "main",
+    {
+      "name": "next",
+      "prerelease": "alpha"
+    },
+    {
+      "name": "beta",
+      "prerelease": "beta"
+    }
+  ],
+  "tagFormat": "@l10nmonster/cli@${version}",
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    {
+      "path": "@semantic-release/changelog",
+      "changelogFile": "CHANGELOG.md"
+    },
+    {
+      "path": "@semantic-release/npm",
+      "npmPublish": true
+    },
+    {
+      "path": "@semantic-release/git",
+      "assets": ["CHANGELOG.md", "package.json"],
+      "message": "chore(release): @l10nmonster/cli@${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

package/README.md

@@ -1,103 +1,421 @@
-## Getting started
+# @l10nmonster/cli
 
-### Installation
+Command-line interface for L10n Monster v3 - continuous localization for the rest of us.
 
-```sh
+## Installation
+
+### From npm
+
+```bash
+npm install -g @l10nmonster/cli
+```
+
+### From source
+
+```bash
 git clone git@github.com:l10nmonster/l10nmonster.git
 cd l10nmonster
-npm i
-npm link
+npm install
+npm run build
+npm link --global @l10nmonster/cli
 ```
 
-Eventually there will be a binary for each platform, but this is still under heavy development.
+## Getting Started
 
-## Basic Operation
+Create a configuration file `l10nmonster.config.mjs` at your project root, then use the CLI commands to manage translations.
 
-```sh
-l10n push
-```
-It will re-read all your source content, figure out what needs translation, and send it to your translator.
+### Basic Configuration
 
-```sh
-l10n status
+```javascript
+// 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'
+  }]
+};
 ```
-It will give you an overview of the state of translation of your project.
 
-```sh
+## v3 Commands
+
+### Core Operations
+
+```bash
+# Analyze source content
 l10n analyze
 ```
-It will analyze your sources and report insights like repeated content in different files and keys.
+Analyzes your sources and reports insights like repeated content, quality metrics, and translation opportunities.
+
+```bash
+# Capture source content snapshot
+l10n source snap
+```
+Creates a snapshot of your source content for translation workflows.
+
+```bash
+# Generate translations
+l10n translate
+```
+Processes translation requests through configured providers and generates translated resources.
+
+```bash
+# Update operations and target resources
+l10n ops update
+```
+Updates target resources with latest translations and manages operation lifecycle.
+
+### Translation Memory
+
+```bash
+# Synchronize TM with providers
+l10n tm syncup
+```
+Uploads completed translations to translation memory stores.
+
+```bash
+# Download translations from TM
+l10n tm syncdown  
+```
+Downloads latest translations from translation memory to local stores.
 
-```sh
-l10n grandfather -q 80
+```bash
+# Export TM data
+l10n tm export
 ```
-TODO: update to Grandfather provider. For all missing translations, it will extract translations from the current translated files and, if present, import them at the specified quality level. This assume translations are faithful translations of the current source (i.e. they didn't become outdated if the source has changed). This is probably only used at the beginning, in order to establish a baseline. Afterwards, translated files are always recreated from the TM and overwritten.
+Exports translation memory data for backup or external processing.
 
-```sh
-l10n leverage -q 70 -u 60
+### Source Management
+
+```bash
+# List source content
+l10n source list
+```
+Lists all detected source content with metadata and statistics.
+
+```bash
+# Query specific content
+l10n source query --filter "*.json"
+```
+Queries source content with filters and search criteria.
+
+```bash
+# Show untranslated content
+l10n source untranslated --target es
+```
+Shows untranslated content for specific target languages.
+
+### Operations Management
+
+```bash
+# View operation details
+l10n ops view
+```
+Displays detailed information about current operations and their status.
+
+```bash
+# Manage jobs
+l10n ops jobs --status pending
+```
+Lists and manages translation jobs by status or other criteria.
+
+```bash
+# Provider operations
+l10n ops providers
 ```
-TODO: update to Repetition provider. For all missing translations, it will look into the TM for translations of the exact same source text but in different resources, while matching or not the string id (called respectively qualified and unqualified repetition). Since reusing translations may lead to a loss of quality, you can choose what quality levels to assign to your specific content. Leveraging can be done on a regular basis before pushing content to translation, or never if it's not safe to do so.
+Shows configured providers and their current status.
 
-```sh
+```bash
+# Delete operations
+l10n ops delete --job-id abc123
+```
+Removes specific operations or jobs from the system.
+
+### Legacy Commands (v2 compatibility)
+
+```bash
+# Legacy push operation
+l10n push
+```
+**Deprecated**: Use `l10n translate` and `l10n ops update` instead.
+
+```bash
+# Legacy pull operation  
 l10n pull
 ```
-If there are pending translations, it will check if they became available and it will fetch them.
+**Deprecated**: Use `l10n tm syncdown` and `l10n ops update` instead.
 
-```sh
-l10n translate
+```bash
+# 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
+
+```bash
+# 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`):
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+export default {
+  providers: [
+    { id: 'leverage', provider: 'InternalLeverage' },
+    { id: 'repetitions', provider: 'Repetition' },
+    { id: 'ai', provider: new GptAgent({ model: 'gpt-4' }) },
+    { id: 'fallback', provider: 'Invisicode' }
+  ]
+};
 ```
-It will generate translated files based on the latest sources and translations in the TM.
 
-### Working files
+## Error Handling
+
+The CLI provides comprehensive error handling with actionable messages:
 
-L10n Monster maintains its working files in a hidden `.l10nmonster` directory at the root of the project. Working files are source-control friendly (json files with newlines) and can be checked in. On the other hand, they can also be destroyed and recreated on the fly if all you want to preserve is translations in your current files.
+```bash
+# Configuration errors
+Error: Configuration file not found: l10nmonster.config.mjs
+Tip: Run 'l10n init' to create a basic configuration
 
-## Demo
+# Provider errors  
+Error: OpenAI API key not configured
+Tip: Set OPENAI_API_KEY environment variable or configure apiKey in provider options
 
-![Demo screen](tty.gif)
+# Operation errors
+Error: Translation job failed for provider 'gpt-4'
+Tip: Check provider configuration and API limits
+```
 
-## Basic Configuration
+## Performance Optimization
 
-At the root of your project there should be a file named `l10nmonster.cjs`. You can create it by hand, or you can use `l10n init` and use one of the configurators to get up and running in no time. Well, that's the plan, it's not implemented yet!
+### Parallel Processing
 
-The configuration must export a class that once instantiated provides the following properties:
+```bash
+# Enable parallel operations
+l10n translate --parallel 4
 
-* `sourceLang`: the default source language
-* `minimumQuality`: this is the minimum required quality for a string to be considered translated (anything below  triggers a request to translate)
-* `source`: a source adapter to read input resources from
-* `resourceFilter`: a filter to process the specific resource format
-* `translationProvider`: a connector to the translation vendor
-* `target`: a target adapter to write translated resources to
-* `adapters`, `filters`, `translators`: built-in helpers (see below)
-* TODO: add the other properties that can be defined
+# Provider-specific parallelism
+l10n ops update --provider-parallel 2
+```
 
-## Advanced CLI
+### Filtering and Batching
 
-The CLI support additional options to control its behavior:
+```bash
+# Process specific file patterns
+l10n translate --filter "*.json"
 
-* `-a, --arg <string>`: this is a user-defined argument that allows to customize the user config behavior
-* `-v, --verbose`: output additional debug information
+# Batch operations by language
+l10n translate --batch-by-language
 
-Some commands also allow additional options. For more information type `l10n help <command>`.
+# Limit operation scope
+l10n source snap --since "2024-01-01"
+```
 
-## Advanced Configuration
+## Integration Examples
 
-There is also additional functionality in the configuration that can be useful, especially in environments with larger teams.
+### CI/CD Pipeline
 
-The the following properties can optionally be defined:
+```yaml
+# GitHub Actions example
+name: Localization
+on: [push, pull_request]
 
-* `jobStore`: a durable persistence adapter to store translations
-* `translationProvider`: this can also be a function that given a job request returns the desired vendor (e.g. `(job) => job.targetLang === 'piggy' ? piggyTranslator : xliffTranslator`)
-* TODO: add the other properties that can be defined
+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
+```
 
-### JSON Job Store
+### NPM Scripts
 
-```js
-this.jobStore = new stores.JsonJobStore({
-    jobsDir: 'translationJobs',
-});
+```json
+{
+  "scripts": {
+    "l10n:analyze": "l10n analyze",
+    "l10n:translate": "l10n translate",
+    "l10n:update": "l10n ops update",
+    "l10n:sync": "l10n tm syncup && l10n tm syncdown"
+  }
+}
 ```
 
-The JSON job store is appropriate for small dev teams where all translations are managed by a single person and there little possibility of conflicts among members. Translation jobs are stored locally in JSON file in a specified folder.
+## Troubleshooting
+
+### Common Issues
+
+1. **Configuration not found**
+   ```bash
+   # Ensure config file exists and has correct name
+   ls l10nmonster.config.mjs
+   ```
+
+2. **Module import errors**
+   ```bash
+   # Verify Node.js version (requires >= 22.11.0)
+   node --version
+   ```
+
+3. **Provider authentication**
+   ```bash
+   # Check environment variables
+   echo $OPENAI_API_KEY
+   ```
+
+4. **Performance issues**
+   ```bash
+   # 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](../v3.md).
+
+## Help and Support
+
+```bash
+# 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
+```
 
-* `jobsDir` is the directory containing translation jobs. It should be kept (e.g. checked into git) as it is needed to regenerate translated resources in a reliable way.
+For more detailed documentation, see:
+- [Main Documentation](../README.md)
+- [Architecture Guide](../architecture.md)
+- [Core Package Documentation](../core/README.md)

package/index.js

@@ -0,0 +1,88 @@
+/* eslint-disable no-underscore-dangle */
+
+import { Command, Argument, Option, InvalidArgumentError } from 'commander';
+import { getVerbosity } from '@l10nmonster/core';
+
+import path from 'path';
+import { readFileSync } from 'fs';
+const cliVersion = JSON.parse(readFileSync(path.join(import.meta.dirname, 'package.json'), 'utf-8')).version;
+
+function intOptionParser(value) {
+    const parsedValue = parseInt(value, 10);
+    if (isNaN(parsedValue)) {
+      throw new InvalidArgumentError('Not an integer');
+    }
+    return parsedValue;
+}
+
+function configureCommand(cmd, Action, l10nRunner) {
+
+    /** @this Command */
+    const actionHandler = async function actionHandler() {
+        const options = this.opts();
+        // Need to hack into the guts of commander as it doesn't seem to expose argument names
+        // @ts-ignore
+        const args = Object.fromEntries(this._args.map((arg, idx) => [
+            arg._name,
+            arg.variadic ? this.args.slice(idx) : this.args[idx]
+        ]));
+        await l10nRunner(async l10n => {
+            await l10n[Action.name]({ ...options, ...args })
+        });
+    };
+    const help = Action.help;
+    cmd.description(help.description).action(actionHandler);
+    help.summary && cmd.summary(help.summary);
+    help.options && help.options.forEach(([ arg, desc, choices]) => {
+        if (choices) {
+            cmd.addOption(new Option(arg, desc).choices(choices));
+        } else {
+            cmd.option(arg, desc);
+        }
+    });
+    help.requiredOptions && help.requiredOptions.forEach(opt => cmd.requiredOption(...opt));
+    help.arguments && help.arguments.forEach(([ arg, desc, choices]) => {
+        if (choices) {
+            cmd.addArgument(new Argument(arg, desc).choices(choices));
+        } else {
+            cmd.argument(arg, desc);
+        }
+    });
+}
+
+export default async function runMonsterCLI(monsterConfig, cliCommand) {
+    const monsterCLI = new Command();
+    monsterCLI
+        .name('l10n')
+        .version(cliVersion, '--version', 'output the current version number')
+        .description('Continuous localization for the rest of us.')
+        .option('-v, --verbose [level]', '0=error, 1=warning, 2=info, 3=verbose', intOptionParser)
+        .option('--regression', 'keep variables constant during regression testing');
+    try {
+        const l10nRunner = async (cb) => {
+            const { verbose, regression } = monsterCLI.opts();
+            await monsterConfig
+                .verbose(verbose)
+                .regression(regression)
+                .run(async mm => await cb(mm.l10n));
+        };
+        monsterConfig.actions.forEach(Action => {
+            const cmd = monsterCLI.command(Action.name);
+            if (Action.subActions) {
+                Action.help.description && cmd.description(Action.help.description);
+                Action.subActions.forEach(subAction => {
+                    const subName = subAction.name.split('_')[1];
+                    const subCmd = cmd.command(subName);
+                    configureCommand(subCmd, subAction, l10nRunner);
+                });
+            } else {
+                configureCommand(cmd, Action, l10nRunner);
+            }
+        });
+        const argv = typeof cliCommand === 'string' ? cliCommand.split(' ') : cliCommand;
+        await monsterCLI.parseAsync(argv);
+    } catch(e) {
+        console.error(`Unable to run CLI: ${(getVerbosity() > 1 ? e.stack : e.message) || e}`);
+        process.exit(1);
+    }
+}

package/l10n.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import runMonsterCLI from './index.js';
+import { resolve, dirname, join } from 'path';
+import { existsSync } from 'fs';
+
+function findConfigFile(startDir = process.cwd()) {
+    let currentDir = resolve(startDir);
+    const configFileName = 'l10nmonster.config.mjs';
+    
+    while (true) {
+        const configPath = join(currentDir, configFileName);
+        if (existsSync(configPath)) {
+            return configPath;
+        }
+        
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            // We've reached the root directory
+            break;
+        }
+        currentDir = parentDir;
+    }
+    
+    return null;
+}
+
+try {
+    const configPath = findConfigFile();
+    if (!configPath) {
+        console.error('Error: Could not find l10nmonster.config.mjs in current directory or any parent directory.');
+        console.error('Please ensure the config file exists in your project root or current working directory.');
+        process.exit(1);
+    }
+    
+    const config = await import(configPath);
+    await runMonsterCLI(config.default);
+} catch (error) {
+    if (error.code === 'ERR_MODULE_NOT_FOUND') {
+        console.error('Error: Could not load l10nmonster.config.mjs - the file may have syntax errors or missing dependencies.');
+        console.error('Details:', error.message);
+    } else if (error.code === 'ENOENT') {
+        console.error('Error: Config file was found but could not be accessed. Please check file permissions.');
+        console.error('Details:', error.message);
+    } else {
+        console.error('Error running l10nmonster CLI:', error.message);
+    }
+    process.exit(1);
+}