Locamorph CLI

Command-line interface for Locamorph translation management.

Installation

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

Quick Start

# 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

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

# 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

# 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

locamorph status         # Show translation coverage

Open in Browser

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

Keys Management

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

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

Configuration

Project Config: locamorph.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:

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

# 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

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