Package Exports

@locamorph/cli
@locamorph/cli/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@locamorph/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

@locamorph/cli