Namespaces

A namespace is a group of keys inside a project. Every key belongs to exactly one, every (language, namespace) pair becomes one JSON file on the CDN, and every project starts with a default namespace.

https://cdn.comvi.io/<project-token>/fr.json             # default namespace
https://cdn.comvi.io/<project-token>/checkout/fr.json    # checkout namespace

When to split

Problem	How a namespace fixes it
Every page loads every translation	Load only the namespaces the current screen needs
Unrelated areas are edited by different people	Give each area its own namespace so filters and hand-offs stay clean
Keys from different surfaces clash or make search noisy	Split by surface (marketing, app, emails)

Stay on default until one of these pinches. Aim for a handful of namespaces, not hundreds, and keep a common one for strings every page loads.

How they behave

• Keys are unique within a namespace. nav.home in common and nav.home in emails are two different keys.
• Imports, exports and Content Deploy each let you pick a subset of namespaces.
• Permissions are project-scoped, not namespace-scoped. A member who can see a project sees all of its namespaces; for strict editorial boundaries, use separate projects.
• Lookups do not cross namespaces at runtime: a key is found in the namespace you asked for, or in the same namespace under a fallback locale, and nowhere else.

Common layouts

common     shared UI (Save, Cancel, error banners)
auth       login, signup, password reset
dashboard  the main product surface
billing    plans, invoices, checkout
emails     transactional email templates

One namespace per top-level feature or route group fits SPAs that already code-split routes. One per consumer (marketing, app, mobile, emails) fits a project that spans very different surfaces. One per owning team (core-product, legal, marketing) makes the hand-off obvious even though roles cannot enforce it. Monorepo with shared namespaces works one layout through in detail.

Create a namespace

1. Open the namespace selector on the Translations page.
2. Choose Create new namespace… at the bottom of the list.
3. Name it in the Add Namespace dialog: lowercase, short, hyphenated if it needs two words (user-settings, not UserSettings).

The name lands in CDN URLs and build pipelines. The dashboard cannot rename or delete a namespace; the REST API can. PATCH renames one, and a name already in use returns NAMESPACE_ALREADY_EXISTS. DELETE removes an empty one; a namespace that still holds keys returns NAMESPACE_NOT_EMPTY, and default returns CANNOT_DELETE_DEFAULT. Deleting a namespace never deletes keys. Without the API, move the keys to a new namespace and stop using the old one.

Move keys between namespaces

Select keys on the Translations page, open More in the selection bar, and choose Change Namespace. Values, history and comments move with the keys. Keys whose name already exists in the target namespace are skipped, and the toast reports how many hit a conflict; rename those and move them again.

Consumers pin the old namespace

An app that hard-coded the old namespace stops finding the moved keys. Update loader configs and build-time pulls before the next deploy.

Next steps

TranslationsEdit keys and values inside a namespace.

Content Deploy / CDNHow namespaces map to CDN URLs.

Import & exportImport or export one namespace at a time.

Consume translationsLoad only the namespaces a screen needs.