Import & Export

Import pulls existing translation files into Comvi. Export downloads the current state as files. Both are used for one-off migration, periodic backups, and hand-offs with external translators or vendors.

For continuous, CI-driven sync against your codebase, use the CLI — it wraps the same operations with config-driven directory layouts.

Supported formats

Direction	Formats	Notes
Import	JSON files, ZIP archive of JSON	Flat or nested key structure, auto-detected
Export	JSON, i18next v4	Flat or nested, pretty or minified

Note

XLIFF 1.2 / 2.0, CSV, and PO (Gettext) export are planned but not yet available. If you are migrating from a platform that only gives you XLIFF, export it to JSON first via a conversion tool, then import.

Importing

The import flow is a guided four-step wizard: upload → map → resolve → commit.

1. Upload

   Go to Import from the sidebar. Drop in individual JSON files or a single ZIP archive containing JSON files. Up to 50 files per batch, 10 MB per file in the dashboard.

   Comvi validates on upload and shows file count and unique-key count.

2. Map files to language + namespace

   Every file needs a language (ICU / CLDR locale code) and a namespace. Comvi auto-assigns when filenames make it obvious — en.json → English, checkout/fr.json → checkout namespace, French.

   You can override any mapping. Bulk actions let you set all files at once or trigger auto-detection again.

   If a file references a language or namespace that doesn’t exist in the project, you can create it from this screen.

3. Resolve conflicts

   A conflict is a key that already exists in the project with a different value. You have three options:

   Strategy	Behaviour
   Keep existing	Current value in Comvi stays. Imported value discarded.
   Use imported	Imported value overwrites the current one.
   Resolve manually	Per-key side-by-side UI to pick the winner.

   Bulk-select all conflicts and apply one strategy, or switch to manual for the ones that matter.

4. Commit

   Click Import. Comvi processes everything in the background and shows per-file results: keys created, updated, skipped, failed.

   A partial failure (e.g. one file has broken JSON) does not roll back the rest. You can retry just the failing files.

Status on import

Imported values land with status based on whether the imported value is empty:

Imported value	Status
Non-empty value	Translated
Empty value	Not translated

Import requires import permission, so it is typically run by an Editor, Manager, Owner, or an API key with write scope.

See Translation Lifecycle for the status model.

Exporting

Go to Export from the sidebar.

1. Pick format

   • JSON — standard output with ICU MessageFormat values preserved
   • i18next v4 — ICU auto-converted to i18next plural / context suffixes

   Options for either format: key structure (flat with dot notation, or nested objects), style (pretty / minified).

2. Pick languages and namespaces

   Tick any subset. Single-namespace exports are common when handing content to an external translator.

3. Filter by status (optional)

   Include only keys with specific statuses (Translated, Not reviewed, Not translated). Toggle whether to include keys with empty values at all.

4. Download

   One selection → one JSON file. Multiple languages or namespaces → a ZIP of <language>/<namespace>.<ext> files.

Tip

Exporting only Translated status is the safest hand-off when sending files to a build system that will ship them to users — use the same filter for CDN production bundles.

Migration playbook

Moving from another TMS? The fast path:

1. Export from the old platform as JSON

   Almost every TMS supports this: Lokalise, Phrase (PhraseApp), Crowdin, Transifex, POEditor. If your source exports flat JSON per language, you’re done. If it exports i18next or vue-i18n JSON, Comvi imports it as-is.

2. Create the Comvi project

   Add the source language and every target language. Do not create keys yet.

3. Import the source language first

   Upload only the source-language files in one import batch. This creates every key with its source value.

4. Import target languages

   Upload the rest. Every key already exists from step 3, so conflicts are always “there’s no existing value” (no conflict) or “pick one” — usually Use imported across the board.

5. Spot-check ICU placeholders

   Non-ICU source formats (i18next plurals, Gettext) are transformed on import. Scan a few plural strings and any key with {} placeholders to confirm.

6. Set up namespaces (if source lacked them)

   Bulk-move keys into namespaces once everything is imported. See Namespaces.

7. Set up TM and glossaries

   A migration import is the ideal moment to seed Translation Memory from TMX and Glossaries from CSV.

Caution

Do not import the same language twice with different conflict strategies on successive runs — it will churn history and confuse reviewers. Make the choice once, commit, verify.

CLI sync

For ongoing sync with a codebase, not a one-off migration, use the CLI:

npx @comvi/cli pull   # Comvi → local files
npx @comvi/cli push   # local files → Comvi

The CLI reads a config file that maps directory layout to project + namespaces, authenticates with an API key, and is designed for CI. See CLI pull and CLI push.

Limits

• 50 files per import batch, 10 MB per file in the dashboard.
• JSON and ZIP are the only import inputs today.
• JSON and i18next v4 are the only export formats today.
• Import is idempotent per commit, but successive imports with different strategies will show up in history.

Troubleshooting

Files didn’t auto-map

Filenames need to contain a recognizable locale code (en, fr-CA, pt-BR) or namespace segment. Rename files or use the bulk mapping dropdown.

ICU placeholders look mangled after import

The source file was probably in i18next format and had non-ICU plural syntax. Comvi converts to ICU on import — spot-check and correct any edge cases. Keys with {{var}} are converted to {var} automatically.

”Use imported” didn’t overwrite the value

Check the importer’s permissions — a translator without review permission can’t overwrite a Translated value directly. Re-run the import as a reviewer or use the manual resolver.

I imported but nothing is on the CDN

Import writes to the platform database, not the CDN. Go to Settings → Content Deploy, enable auto-deploy (or click Deploy Now) to push the imported content to the edge. See CDN Deployment.

Related

CLI pull Automated download in CI/CD.

CLI push Automated upload from a codebase.

Namespaces How imported files map to namespaces.

Translation Lifecycle Which status imported values end up in.