Core Concepts

If you’ve used a TMS before, most of Comvi will feel familiar: an organization owns projects, each project has its own languages, keys, translations, and CDN distribution. This page covers the parts where Comvi is opinionated or differs from what you might expect.

Projects are isolated

A project represents one translatable surface — typically one application or website. Languages, namespaces, keys, API keys, and the CDN distribution are all project-scoped. Nothing crosses project boundaries except Translation Memory.

If two surfaces share almost all copy, one project with multiple namespaces is usually better than two projects. If they have separate release cycles or owners, prefer separate projects.

Languages use CLDR codes with underscores

Locale codes follow ICU / CLDR conventions — underscore-separated region and script: en, de, pt_BR, zh_Hant. Not BCP-47 hyphens.

Note

The source language is set when you create the project and cannot be changed afterwards. Pick deliberately — machine translation quality and translation memory matches depend on it.

Namespaces are a deployment boundary

A namespace is a group of keys that ships together. Every (language, namespace) pair becomes one JSON bundle on the CDN — so namespaces aren’t just folders, they’re how you code-split translations. See CDN for the URL layout.

Reasons to add more than the default namespace:

• Code-split — an app loads only what a given screen needs
• Organize — keep large projects navigable (auth, dashboard, emails)
• Delegate — different teams own different namespaces

Tip

Small project? Stay on the single default namespace. Introduce more only when code-splitting or ownership pressure appears.

Keys are opaque strings

The platform treats keys as opaque strings. Dot notation is a readability convention, not nesting:

greeting
nav.home
errors.not_found

A key belongs to exactly one namespace and carries a value per language, plus optional description/screenshots for translator context. Values support ICU MessageFormat:

You have {count, plural, one {# message} other {# messages}}.

Status is orthogonal to publishing

Every value has a status (not_translated → not_reviewed → translated) that tracks where it is in the review pipeline. Publishing is a separate, independent action — not a status. You can publish not_reviewed values, and a translated value isn’t live until you publish. The full state machine: Translation lifecycle.

API keys are project-scoped machine credentials

An API key authenticates the CLI, CI, and any automation against the REST API. Keys are scoped to a single project and carry their own permissions, independent of any user — rotate or revoke them without touching member accounts. Human users authenticate with sessions instead — see Authentication.

Webhooks go the other direction (Comvi calling your server) and are verified with an HMAC signature, not an API key.

Members and their roles on projects are covered on Roles & Permissions.

Next steps

Your First Project Walk through creating a project end to end.

Consume Translations Load published bundles into any app or runtime.