npm package: @locamorph/cli
Description: Command-line interface for Locamorph translation management
Author: Locamorph
Latest version: 1.0.0

# Locamorph CLI

Command-line interface for Locamorph translation management.

## Installation

```bash
# Install via npm
npm install -g @locamorph/cli
```

## Quick Start

```bash
# Configure your key preferrably in your bash profile
export LOCAMORPH_API_KEY=sk_your_api_key

# Initialize your project when your cwd is the root dir of the project
locamorph init

# Download translations
locamorph download
locamorph download --zip

# Upload translations
locamorph upload
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `LOCAMORPH_API_KEY` | API key for authentication |
| `LOCAMORPH_PROJECT_ID` | Default project ID |
| `LOCAMORPH_BASE_URL` | API base URL |

## Commands

### Project Management

```bash
locamorph init [project-id]   # Create locamorph.yaml config
locamorph projects            # List accessible projects
locamorph projects show <id>  # Show project details
locamorph projects show <id> --json  # Output as JSON
```

Example output for `locamorph projects`:
```
Projects (3)

ID                                    Name                 Languages           Progress              Keys
───────────────────────────────────────────────────────────────────────────────────────────────────────────
c1627915-1d88-4dbc-97a0-8c23a3c84763  Dev Project          en, de, ar, 1 more  [█████████████████░░░]  250
62dcb31c-c44d-49c5-91ec-53e391c77c62  Empty Project        en, ar              [░░░░░░░░░░░░░░░░░░░░]  0
8d738a98-c763-45ea-a77e-75e69a7b5f73  My Test Project      en, de, tr          [██████░░░░░░░░░░░░░░]  2154

Progress bar: █ translated | █ pending review | █ needs revision | ░ untranslated
```

### Download Translations

```bash
# Download all languages
locamorph download

# Download specific language
locamorph download en

# Download multiple languages
locamorph download en de fr

# Options
locamorph download --skip-untranslated  # Skip keys with no translation
locamorph download --only-verified      # Only verified translations
locamorph download --dir ./i18n         # Translations directory (overrides translations_dir)
locamorph download --format json|yaml   # File format
locamorph download --file-structure "{LANG_ISO}.json"  # File naming pattern
locamorph download --dryrun             # Preview changes without downloading
locamorph download --cleanup            # Delete existing files before writing
locamorph download --zip                # Download as a single zip file
```

### Upload Translations

```bash
# Upload all languages (adds new keys only)
locamorph upload

# Upload specific language
locamorph upload en

# Upload multiple languages
locamorph upload en ua

# Options
locamorph upload --dir ./i18n           # Translations directory (overrides translations_dir)
locamorph upload --format json|yaml     # File format
locamorph upload --file-structure "{LANG_ISO}.json"  # File naming pattern
locamorph upload --source "./src/**/locale/*.json"   # Source mode: glob pattern for base language
locamorph upload --include "**/*.json"  # Include file patterns (relative to dir)
locamorph upload --exclude "**/backup/**" # Exclude file patterns (relative to dir)
locamorph upload --update               # Update existing translations (default: only add new)
locamorph upload --auto-verify          # Auto-verify uploaded translations
locamorph upload --delete-removed       # Delete keys not present in local files
locamorph upload --delete-removed-files # Delete files not present locally
locamorph upload --dryrun               # Preview changes without uploading
locamorph upload --json                 # Output results as JSON
locamorph upload --verbose              # Show detailed key changes
```

Example output:
```
Uploaded translations for "Dev Project"
┌───────────────────┬───────┬─────────┬─────────┐
│                   │ Added │ Updated │ Removed │
├───────────────────┼───────┼─────────┼─────────┤
│ English(en)       │ 1     │ 1       │ 12      │
│ Ukrainian(ua)     │ 1     │ 1       │ 12      │
├───────────────────┼───────┼─────────┼─────────┤
│ Total             │ 2     │ 2       │ 24      │
└───────────────────┴───────┴─────────┴─────────┘

Run with --verbose to see details.
```

### Status

```bash
locamorph status         # Show translation coverage
```

### Open in Browser

```bash
locamorph open              # Open current project in browser
locamorph open <project-id> # Open specific project in browser
```

### Keys Management

```bash
locamorph keys                        # List translation keys
locamorph keys add <key> --value "x"  # Add new key
locamorph keys delete <key>           # Delete key
locamorph keys search "term"          # Search keys
locamorph keys show <key>             # Show key details
```

### Languages Management

```bash
locamorph languages                   # List project languages
locamorph languages add <code>        # Add language
locamorph languages remove <code>     # Remove language
```

## Configuration

### Project Config: `locamorph.yaml`

```yaml
project_id: "uuid-here"
translations_dir: "./locales"       # Base directory for upload/download
format: json                        # json, yaml
file_structure: "{LANG_ISO}.json"   # or "{LANG_ISO}/{FILE}.json" for multi-file

# Optional language filter
languages:
  - en
  - de
  - fr

# File patterns relative to translations_dir
include:
  - "**/*.json"                     # Include only JSON files
exclude:
  - "**/backup/**"                  # Exclude backup directory

# Key filtering patterns
includeKeys:
  - "common.*"
excludeKeys:
  - "internal.*"

# Upload settings (all defaults shown)
upload:
  on_conflict: skip             # skip (default), overwrite
  delete_removed: false         # Delete keys not present in local files (default: false)
  delete_removed_files: false   # Delete files not present locally (default: false)
  auto_verify: false            # Auto-verify uploaded translations (default: false)

# Download settings (all defaults shown)
download:
  empty_translations: skip      # skip (default), include
  cleanup: false                # Delete existing files before writing (default: false)
```

### Source Mode (Base Language Import)

When you want to import files only to the base language (e.g., extracting keys from source code), use the `source` option with a glob pattern:

```yaml
# In locamorph.yaml
source: "./src/**/locale/*.json"    # Glob pattern to find source files
```

```bash
# Or via CLI
locamorph upload --source "./src/**/locale/*.json"
```

**How it works:**
- The `source` option is a **glob pattern** that determines which files to import
- All matched files are uploaded to the **base language only**
- File names are extracted from the basename (e.g., `common.json` → file scope `common`)
- The `file_structure` option is **NOT used** for file detection in source mode
- Language arguments are ignored in source mode
- Useful for: extracting keys from default strings, importing from a monorepo source directory

**Example:** With pattern `./src/**/locale/*.json`, files like:
- `./src/components/locale/common.json` → file scope `common`
- `./src/features/auth/locale/auth.json` → file scope `auth`

All will be imported to your base language (e.g., English).

### User Config: `~/.locamorph/config.yaml`

```yaml
api_key: sk_xxx
api_url: https://api.locamorph.com
default_format: json
color: auto
verbose: false
```

## Global Options

| Option | Short | Description |
|--------|-------|-------------|
| `--api-key` | `-k` | API key for authentication |
| `--project-id` | `-p` | Project ID (overrides config) |
| `--config` | `-c` | Path to config file |
| `--output-format` | `-o` | Output format: text, json |
| `--quiet` | `-q` | Minimal output |
| `--verbose` | `-v` | Verbose output |
| `--no-color` | | Disable colored output |
| `--help` | `-h` | Show help |
| `--version` | | Show version |

## License

MIT