Lezu CLI

The official command-line interface for Lezu translation management platform.

Installation

# Use directly with npx (recommended)
npx lezu

# Or install globally
npm install -g lezu

Quick Start

1. Interactive Mode (recommended for first-time users):

   npx lezu

2. Direct Commands:

   # Download translations
   npx lezu load --project=YOUR_PROJECT_ID --api-key=YOUR_API_KEY
   
   # Add a new translation key
   npx lezu add --key=common.save --en="Save" --es="Guardar"
   
   # Get project information
   npx lezu get project
   
   # Create a release
   npx lezu release create --version=1.0.0

Configuration

Environment Variables

LEZU_PROJECT_ID=your_project_id
LEZU_API_KEY=your_api_key
LEZU_API_URL=https://api.lezu.app  # Optional, defaults to production

# For local development:
# LEZU_API_URL=http://localhost:8787

Configuration File

Create a .lezurc or .lezurc.json file in your project root:

{
  "projectId": "your_project_id",
  "apiKey": "your_api_key",
  "apiUrl": "https://api.lezu.app",  // Optional, for custom API endpoints
  "dest": "./src/i18n",
  "format": "json",
  "environment": "production"
}

Configuration Priority

1. Command-line arguments (highest priority)
2. Environment variables
3. Configuration file
4. Defaults (lowest priority)

Commands

lezu load

Download translation files from Lezu.

Usage:

lezu load [options]

Options:

• -p, --project <id> - Project ID
• -k, --api-key <key> - API key
• -d, --dest <path> - Destination folder (default: ./src/i18n)
• -f, --format <format> - Output format: json, js, ts, yaml, po (default: json)
• -l, --languages <languages> - Comma-separated list of languages to download
• -r, --release <id> - Specific release ID to download
• -e, --environment <env> - Environment (default: production)
• --flatten - Flatten nested keys (e.g., common.save instead of { common: { save: "..." } })
• --namespace - Use namespace folder structure (locales/en.json)
• --include-empty - Include empty translations
• -w, --watch - Watch for changes and auto-update
• --watch-interval <ms> - Watch interval in milliseconds (default: 5000)
• --api-url <url> - API URL (default: https://api.lezu.app)

Examples:

# Basic usage
lezu load --project=proj_123 --api-key=lk_456

# Download specific languages only
lezu load --languages=en,es,fr

# Download from a specific release
lezu load --release=rel_789

# Flatten keys and output as TypeScript
lezu load --flatten --format=ts

# Export as gettext .po files
lezu load --format=po

# Watch mode for development
lezu load --watch --watch-interval=2000

Output Formats:

• JSON (default):

  {
    "common": {
      "save": "Save",
      "cancel": "Cancel"
    }
  }

• JavaScript (ES modules):

  export default {
    common: {
      save: "Save",
      cancel: "Cancel"
    }
  }

• TypeScript:

  export default {
    common: {
      save: "Save",
      cancel: "Cancel"
    }
  } as const

• YAML:

  common:
    save: Save
    cancel: Cancel

• Gettext (.po):

  # Translation file for en
  # Generated by Lezu CLI on 2024-01-15T10:30:00.000Z
  msgid ""
  msgstr ""
  "Language: en\n"
  "MIME-Version: 1.0\n"
  "Content-Type: text/plain; charset=UTF-8\n"
  "Content-Transfer-Encoding: 8bit\n"
  "Generated-By: Lezu CLI\n"
  
  msgid "common.save"
  msgstr "Save"
  
  msgid "common.cancel"
  msgstr "Cancel"

lezu add

Add a new translation key with values.

Usage:

lezu add --key=<key> [options]

Options:

• -k, --key <key> - Required. Translation key (e.g., "common.save")
• -v, --value <value> - Value for the source language
• --en <value> - English translation
• --es <value> - Spanish translation
• --fr <value> - French translation
• --de <value> - German translation
• --nl <value> - Dutch translation
• --it <value> - Italian translation
• --pt <value> - Portuguese translation
• --ru <value> - Russian translation
• --ja <value> - Japanese translation
• --ko <value> - Korean translation
• --zh <value> - Chinese translation
• --ar <value> - Arabic translation
• -d, --description <desc> - Description for the translation key
• --auto - Auto-translate to all enabled languages using AI
• -p, --project <id> - Project ID
• -a, --api-key <key> - API key

Examples:

# Add key with specific translations
lezu add --key=common.save --en="Save" --es="Guardar" --fr="Enregistrer"

# Add key with auto-translation
lezu add --key=common.delete --en="Delete" --auto

# Add key with description
lezu add --key=error.validation --description="Validation error message" --en="This field is required"

Subscription Requirements:

• Free: Cannot add keys
• Basic+: Can add keys and translations
• Pro+: Can add keys with auto-translation

lezu get

Get information about your project.

lezu get project

Get project information and statistics.

Usage:

lezu get project [options]

Options:

• --stats - Include detailed statistics
• --json - Output as JSON
• -p, --project <id> - Project ID
• -a, --api-key <key> - API key

Example:

lezu get project --stats

lezu get languages

List all languages in your project.

Usage:

lezu get languages [options]

Options:

• --include-disabled - Include disabled languages
• --json - Output as JSON
• -p, --project <id> - Project ID
• -a, --api-key <key> - API key

Example:

lezu get languages --include-disabled

lezu get releases

List all releases in your project.

Usage:

lezu get releases [options]

Options:

• -e, --environment <env> - Environment (default: production)
• --limit <n> - Limit number of results (default: 10)
• --json - Output as JSON
• -p, --project <id> - Project ID
• -a, --api-key <key> - API key

Example:

lezu get releases --environment=staging --limit=20

lezu release

Manage releases.

lezu release create

Create a new release.

Usage:

lezu release create [options]

Options:

• -v, --version <version> - Release version (e.g., "1.0.0")
• -n, --name <name> - Release name
• -d, --description <desc> - Release description
• -e, --environment <env> - Environment (default: production)
• --reviewed-only - Include only reviewed translations
• --set-current - Set this release as the current release
• --timestamp <iso> - Specific timestamp for the release (ISO format)
• --languages <langs> - Comma-separated list of languages to include
• --json - Output as JSON
• -p, --project <id> - Project ID
• -a, --api-key <key> - API key

Examples:

# Create a basic release
lezu release create --version=1.0.0

# Create release with specific timestamp and set as current
lezu release create --version=1.1.0 --timestamp=2024-01-15T10:00:00Z --set-current

# Create release with only reviewed translations
lezu release create --version=1.0.1 --reviewed-only --name="Hotfix Release"

Subscription Requirements:

• Free: Cannot create releases
• Basic: Cannot create releases
• Pro+: Can create releases

lezu release current <releaseId>

Set a release as current.

Usage:

lezu release current <releaseId> [options]

Example:

lezu release current rel_123abc456def

lezu release list

List all releases (alias for lezu get releases).

API Keys and Authentication

Getting an API Key

1. Go to Lezu Dashboard
2. Navigate to your project settings
3. Go to the "API Keys" section
4. Click "Create API Key"
5. Copy the generated key (it will only be shown once)

API Key Scopes

API keys have different capabilities based on your subscription:

Free Plan:

• ✅ Download translations (load)
• ✅ Get project information (get)
• ❌ Add keys (add)
• ❌ Create releases (release create)

Basic Plan:

• ✅ All Free features
• ✅ Add translation keys (add)
• ✅ Update translations
• ❌ Create releases

Pro+ Plans:

• ✅ All Basic features
• ✅ Create releases (release create)
• ✅ Auto-translation with AI
• ✅ Higher rate limits

Rate Limits

Rate limits are applied per API key per minute:

| Plan | Requests/min | Translations/min | |------|-------------|------------------| | Free | 50 | 10 | | Basic | 500 | 100 | | Pro | 5,000 | 1,000 | | Team | 10,000 | 2,000 | | Enterprise | 50,000 | 10,000 |

Error Handling

The CLI provides clear error messages for common issues:

• 401 Unauthorized: Invalid API key
• 402 Payment Required: Subscription required or expired
• 403 Forbidden: Feature requires subscription upgrade
• 404 Not Found: Project or resource not found
• 429 Too Many Requests: Rate limit exceeded

Troubleshooting

Common Issues

"Configuration errors: Project ID is required"

• Set LEZU_PROJECT_ID environment variable
• Or use --project flag
• Or add projectId to .lezurc file

"API request failed: 401 Unauthorized"

• Check your API key is correct
• Ensure the API key hasn't expired
• Verify the API key belongs to the correct project

"Subscription upgrade required"

• Your current plan doesn't support this feature
• Upgrade your subscription at app.lezu.app/billing

"Rate limit exceeded"

• Wait for the rate limit window to reset
• Consider upgrading your subscription for higher limits

Debug Mode

Set the DEBUG environment variable to see detailed logs:

DEBUG=lezu* npx lezu load

Integration Examples

CI/CD Pipeline

# GitHub Actions example
- name: Download translations
  run: npx lezu load
  env:
    LEZU_PROJECT_ID: ${{ secrets.LEZU_PROJECT_ID }}
    LEZU_API_KEY: ${{ secrets.LEZU_API_KEY }}

Package.json Scripts

{
  "scripts": {
    "i18n:pull": "lezu load",
    "i18n:watch": "lezu load --watch",
    "i18n:release": "lezu release create --version=$npm_package_version"
  }
}

Pre-build Hook

{
  "scripts": {
    "prebuild": "lezu load --format=js",
    "build": "vite build"
  }
}

Support

• 📖 Documentation
• 💬 Discord Community
• 📧 Email Support
• 🐛 Report Issues

License

MIT License - see LICENSE file for details.