comvi pull

The comvi pull command downloads translations from the Comvi platform and writes them to local JSON files. Use it to keep your local translation files in sync with the platform, generate static bundles for production, or seed translations for offline development.

Prerequisites

You need a .comvirc.json file in your project root and an API key. Prefer COMVI_API_KEY for the key:

{
  "apiBaseUrl": "https://api.comvi.io",
  "translationsPath": "./src/locales",
  "fileTemplate": "{languageTag}/{namespace}.json",
  "format": "json"
}

Basic Usage

comvi pull

This downloads all languages and all namespaces from your project and writes them to the configured translationsPath.

Options

comvi pull [options]

Option	Alias	Default	Description
`--config`	`-c`	`.comvirc.json`	Path to the Comvi config file
`--lang`	`-l`	All project languages	Comma-separated list of language tags to download
`--ns`	`-n`	All namespaces	Comma-separated list of namespaces to download
`--path`	`-p`	`.comvirc.json` → `translationsPath`	Output directory for translation files
`--empty-dir`		`.comvirc.json` → `pull.emptyDir`	Clear the translations directory before writing files

Output File Structure

Downloaded files are organized by language and namespace:

src/locales/
├── en/
│   ├── common.json
│   ├── auth.json
│   └── dashboard.json
├── de/
│   ├── common.json
│   ├── auth.json
│   └── dashboard.json
└── fr/
    ├── common.json
    ├── auth.json
    └── dashboard.json

Each file contains the translation key-value pairs for that language and namespace:

{
  "greeting": "Hello, {name}!",
  "nav.home": "Home",
  "nav.settings": "Settings"
}

The SDK CLI currently writes JSON using the configured fileTemplate and format: "json".

{
  "greeting": "Hello, {name}!",
  "nav": {
    "home": "Home",
    "settings": "Settings"
  }
}

Pulling Specific Locales

Download only the languages you need:

# Pull only English and German
comvi pull --lang en,de

# Pull only French
comvi pull -l fr

Pulling Specific Namespaces

Download only certain namespaces:

# Pull only the common namespace
comvi pull --ns common

# Pull common and auth namespaces
comvi pull -n common,auth

Cleaning Stale Files

If you remove a language or namespace from your project on the platform, the local files remain. Use --clean to delete files that no longer have a matching resource on the platform:

comvi pull --clean

CI/CD Usage

Pull translations as part of your build pipeline so your production bundle always includes the latest translations:

name: Build
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx comvi pull
        env:
          COMVI_API_KEY: ${{ secrets.COMVI_API_KEY }}
      - run: npm run build

This ensures that every build uses the most recent published translations without committing translation files to your repository.

Configuration File Reference

All pull options can also be set in .comvirc.json so you do not have to pass them every time:

{
  "apiBaseUrl": "https://api.comvi.io",
  "translationsPath": "./src/locales",
  "fileTemplate": "{languageTag}/{namespace}.json",
  "format": "json",
  "pull": {
    "emptyDir": false
  }
}

Command-line flags override the config file values. For example, comvi pull --lang en pulls only English.

Next Steps

comvi push — upload local translations to the platform
comvi typegen — generate TypeScript types from pulled translations
CLI Overview — all CLI commands and global configuration
CI/CD Integration — full pipeline examples