@vogonapp/cli

Command-line interface for Vogon translation management. Sync your FormatJS/react-intl messages with Vogon for translation, review, and collaboration.

Installation

npm install -g @vogonapp/cli

Or with other package managers:

pnpm add -g @vogonapp/cli
yarn global add @vogonapp/cli

Quick Start

1. Initialize your project:

   vogon init

   This opens a browser for authentication and creates vogon.config.json.

2. Configure message paths:

   Edit vogon.config.json to point to your message files, or run:

   vogon configure

3. Push messages to Vogon:

   vogon push

4. Pull translations:

   vogon pull

Commands

| Command | Description | |---------|-------------| | vogon init | Initialize project and authenticate | | vogon login | Re-authenticate with Vogon | | vogon configure | Scan for message files and update config | | vogon push | Upload source messages to Vogon | | vogon pull | Download translations from Vogon | | vogon import <locale> <file> | Import translations from a JSON file | | vogon status | Show translation status |

Command Options

vogon init

• -u, --api-url <url> - Vogon API URL (default: https://vogon.app)
• -k, --key <key> - API key (for CI/CD environments)
• -l, --login - Skip prompts and open browser directly

vogon push

• -b, --branch <name> - Push to a specific branch
• -t, --auto-translate - Auto-translate new messages with DeepL

vogon pull

• -l, --locale <code> - Pull only a specific locale
• -b, --branch <name> - Pull from a specific branch

vogon import

• -b, --branch <name> - Import to a specific branch

vogon status

• -b, --branch <name> - Show status for a specific branch

Configuration

The CLI uses vogon.config.json in your project root:

{
  "projectId": "your-project-id",
  "apiUrl": "https://vogon.app",
  "packages": [
    {
      "name": "main",
      "messagesPath": "./src/lang/en.json",
      "outputPath": "./src/lang/{locale}.json"
    }
  ]
}

Configuration Options

• projectId - Your Vogon project ID (set automatically during init)
• apiUrl - Vogon API URL (default: https://vogon.app)
• packages - Array of message package configurations:
  • name - Package identifier
  • messagesPath - Path to source messages (FormatJS JSON format)
  • outputPath - Output path template for translations. Use {locale} as placeholder.

Multiple Packages

For monorepos or projects with multiple message files:

{
  "projectId": "your-project-id",
  "apiUrl": "https://vogon.app",
  "packages": [
    {
      "name": "web",
      "messagesPath": "./apps/web/src/messages/en.json",
      "outputPath": "./apps/web/src/messages/{locale}.json"
    },
    {
      "name": "mobile",
      "messagesPath": "./apps/mobile/src/lang/en.json",
      "outputPath": "./apps/mobile/src/lang/{locale}.json"
    }
  ]
}

Authentication

Browser Login (Recommended)

Run vogon init or vogon login to authenticate via browser. Credentials are stored in ~/.vogon/credentials.json.

Environment Variable

For CI/CD pipelines, set the VOGON_API_KEY environment variable:

export VOGON_API_KEY=your-api-key
vogon push

Generate API keys in your project settings at https://vogon.app/dashboard.

API Key via Flag

vogon init --key your-api-key

Branch Workflow

Vogon supports branch-based workflows for managing translation changes:

# Push to a feature branch
vogon push --branch feature/new-onboarding

# Pull from the branch
vogon pull --branch feature/new-onboarding

# Check status
vogon status --branch feature/new-onboarding

Message Format

The CLI works with FormatJS/react-intl JSON message format:

{
  "greeting": {
    "defaultMessage": "Hello, {name}!",
    "description": "Greeting shown to users"
  },
  "items.count": {
    "defaultMessage": "{count, plural, one {# item} other {# items}}",
    "description": "Item count label"
  }
}

Requirements

• Node.js 18 or later

License

MIT