@vogonapp/cli

Command-line interface for Vogon translation management. Sync your i18n messages with Vogon for translation, review, and collaboration.

Supported formats: FormatJS/react-intl, next-intl, i18next

Installation

npm install -g @vogonapp/cli

Or with other package managers:

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

Quick Start

# Initialize and auto-detect your message files
vogon init

# Push messages to Vogon
vogon push

# Pull translations
vogon pull

The init command will:

1. Authenticate via browser (or use an existing API key)
2. Detect workspace configuration (pnpm/npm workspaces, monorepos)
3. Scan for message files and identify their format
4. Generate vogon.config.json with your confirmation

Commands

| Command | Description | |---------|-------------| | vogon init | Initialize project with smart auto-detection | | vogon login | Re-authenticate with Vogon | | vogon extract | Extract messages from source files | | vogon push | Upload source messages to Vogon | | vogon pull | Download translations from Vogon | | vogon status | Show translation progress | | vogon validate | Validate ICU syntax in translation files | | vogon import | Import translations from a JSON file | | vogon branch list | List Vogon branches | | vogon branch delete | Delete a Vogon branch | | vogon translator-urls | Generate shareable translator URLs |

Command Reference

vogon init

Initialize a project with smart configuration detection.

vogon init              # Interactive mode
vogon init -y           # Auto-accept detected config
vogon init --no-scan    # Skip scanning, use defaults
vogon init -k <key>     # Use API key directly (for CI)

Options:

• -u, --api-url <url> - Vogon API URL (default: https://vogon.app)
• -k, --key <key> - API key (skips browser auth)
• -l, --login - Open browser directly without prompts
• -y, --yes - Accept detected config without prompting (for CI)
• --no-scan - Skip message file scanning, use default paths

What it detects:

• Workspace type (pnpm, npm/yarn workspaces, single package)
• Message files in each package
• Message format (FormatJS, next-intl flat, i18next)
• Suggested output paths based on conventions

vogon extract

Extract messages from source files using static analysis.

vogon extract                    # Extract for all packages
vogon extract --package web      # Extract for specific package
vogon extract --no-write         # Preview to stdout

Options:

• -p, --pattern <glob> - Override source file pattern
• --no-write - Output to stdout instead of writing files
• --package <name> - Extract only for a specific package

vogon push

Upload source messages to Vogon. Automatically detects the current git branch.

vogon push                           # Push (auto-detects git branch)
vogon push -t                        # Auto-translate new messages

Options:

• -t, --auto-translate - Auto-translate new messages with DeepL

vogon pull

Download translations from Vogon.

vogon pull                    # Pull all locales
vogon pull -l fr              # Pull French only
vogon pull -b feature/new-ui  # Pull from branch

Options:

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

vogon status

Show translation progress.

vogon status              # Show status for main
vogon status -b my-branch # Show status for branch
vogon status -c           # Exit code 1 if incomplete (for CI)

Options:

• -b, --branch <name> - Show status for a specific branch
• -c, --check - Exit with code 1 if translations are incomplete

vogon validate

Validate ICU syntax in translation files.

vogon validate                          # Validate all locales
vogon validate -l fr                    # Validate French only
vogon validate -f github-actions        # GitHub Actions annotation format

Options:

• -l, --locale <code> - Validate only this locale
• -f, --format <format> - Output format: human (default), json, github-actions

vogon branch list

List Vogon branches.

vogon branch list                # List active branches
vogon branch list -s all         # List all branches
vogon branch list -f json        # JSON output

Options:

• -s, --status <status> - Filter: active (default), merged, closed, all
• -f, --format <format> - Output: table (default), json, plain

vogon branch delete

Delete a Vogon branch.

vogon branch delete -b feature/old
vogon branch delete -b feature/old --force  # Skip confirmation

Options:

• -b, --branch <name> - Branch name to delete
• --force - Skip confirmation prompt

vogon translator-urls

Generate shareable URLs for translators.

vogon translator-urls -b feature/new-ui
vogon translator-urls -b main -f json

Options:

• -b, --branch <name> - Branch to generate URLs for (required)
• -f, --format <format> - Output: markdown (default), json, plain

vogon import

Import translations from a JSON file.

vogon import fr ./translations/fr.json
vogon import es ./spanish.json -b feature/new

Options:

• -b, --branch <name> - Import to 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",
      "sourcePattern": "src/**/*.{ts,tsx}",
      "messageFormat": "formatjs"
    }
  ]
}

Configuration Options

| Field | Description | |-------|-------------| | projectId | Your Vogon project ID (set during init) | | apiUrl | Vogon API URL (default: https://vogon.app) | | packages | Array of package configurations |

Package Options

| Field | Description | |-------|-------------| | name | Package identifier | | messagesPath | Path to source messages file | | outputPath | Output path template ({locale} placeholder) | | sourcePattern | Glob for source files (used by extract) | | sourceRoot | Root path for resolving source locations | | messageFormat | formatjs, flat, or namespaced |

Monorepo Example

{
  "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",
      "sourcePattern": "apps/web/src/**/*.{ts,tsx}"
    },
    {
      "name": "mobile",
      "messagesPath": "./apps/mobile/src/lang/en.json",
      "outputPath": "./apps/mobile/src/lang/{locale}.json",
      "sourcePattern": "apps/mobile/src/**/*.{ts,tsx}"
    }
  ]
}

Authentication

Browser Login (Recommended)

vogon init    # or
vogon login

Opens a browser for authentication. Credentials are stored in ~/.vogon/credentials.json.

Environment Variable (CI/CD)

export VOGON_API_KEY=your-api-key
vogon push

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

API Key Flag

vogon init -k your-api-key

Message Formats

FormatJS / react-intl

{
  "greeting": {
    "defaultMessage": "Hello, {name}!",
    "description": "Greeting shown to users"
  }
}

next-intl (flat)

{
  "greeting": "Hello, {name}!",
  "items.count": "{count, plural, one {# item} other {# items}}"
}

i18next (namespaced)

{
  "common": {
    "greeting": "Hello, {{name}}!"
  }
}

CI/CD Integration

GitHub Actions Example

name: Translations
on: [push]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install -g @vogonapp/cli

      - name: Push messages
        run: vogon push
        env:
          VOGON_API_KEY: ${{ secrets.VOGON_API_KEY }}

      - name: Check translation status
        run: vogon status --check
        env:
          VOGON_API_KEY: ${{ secrets.VOGON_API_KEY }}

      - name: Validate ICU syntax
        run: vogon validate -f github-actions

Branch Workflow

- name: Push to feature branch
  run: vogon push -b ${{ github.head_ref }}
  env:
    VOGON_API_KEY: ${{ secrets.VOGON_API_KEY }}

Requirements

• Node.js 18 or later

License

MIT