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:

.comvirc.json

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

Tip

Store your API key in the COMVI_API_KEY environment variable instead of the config file. The CLI reads from the environment automatically, so you can safely commit .comvirc.json without secrets.

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
--locale	-l	All project locales	Comma-separated list of locale 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

Files are written per the configured fileTemplate. With the default template ({namespace}/{languageTag}.json), the default namespace is written at the root as {languageTag}.json, and every other namespace gets its own subdirectory:

src/locales/
├── en.json            # default namespace (root)
├── de.json
├── fr.json
├── common/
│   ├── en.json
│   ├── de.json
│   └── fr.json
└── auth/
    ├── en.json
    ├── de.json
    └── fr.json

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

src/locales/common/en.json

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

The CLI writes JSON using the configured fileTemplate and format: "json". A custom template is matched literally.

src/locales/common/en.json (nested)

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

Pulling Specific Locales

Download only the locales you need:

# Pull only English and German
comvi pull --locale 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

Clearing the Local Directory

Use --empty-dir to wipe the translations directory before writing new files. This removes any local files that are no longer present on the platform:

comvi pull --empty-dir

Caution

--empty-dir deletes all files in the translations directory before writing. If you have local-only translation files that are not on the platform, they will be removed.

CI/CD Usage

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

.github/workflows/build.yml

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: 22
      - 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.

Tip

Pair comvi pull with comvi typegen in your CI pipeline to keep TypeScript types in sync with the latest translations.

Configuration File Reference

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

.comvirc.json

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

Command-line flags override the config file values. For example, comvi pull --locale 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