Namespaces

A namespace is a group of translation keys inside a project. Every key belongs to exactly one namespace. Namespaces are the deployment boundary on the CDN — each (language, namespace) pair becomes one JSON file — and they are the basic unit of ownership and code-splitting.

When to use them

You do not need namespaces for a small project. Every project starts with a default namespace, and until you feel one of the problems below, everything can live there:

Problem you have	How a namespace fixes it
Loading all translations on every page makes payloads large	Load only the namespaces the current screen needs
Unrelated parts of the product are edited by different people	Put each area in its own namespace, assign reviewers per area
Keys from totally different surfaces clash or make search noisy	Split by surface (marketing, app, emails) so the editor stays navigable

If none of those pinch, stay on default. Introduce namespaces when one of them starts to matter — not preemptively.

How it works

• Keys are unique within a namespace, not across a whole project. nav.home can exist in common and in emails; they are two different keys.
• Each namespace ships as a separate JSON file per language on publish — e.g. cdn.comvi.io/<token>/checkout/fr.json. The default namespace is served at the project root: cdn.comvi.io/<token>/fr.json.
• Imports, exports, and CDN publish settings all let you pick a subset of namespaces.
• Permissions are project-scoped, not namespace-scoped. To restrict editing by area, use separate projects.

Strategy guides

The right split depends on who owns what and how your app loads.

By feature / route

The most common choice. Namespace per top-level feature or route group:

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

Fits SPAs that already code-split routes: each route loads its own namespace plus common.

By surface

If one project spans very different consumers, split by consumer:

marketing  — landing pages, docs site copy
app        — the product itself
mobile     — strings only the mobile app uses
emails     — transactional copy

By team or workflow

If separate teams or external agencies own different areas:

core-product   — in-house
legal          — reviewed by legal team only
marketing      — reviewed by marketing team
support-email  — support team writes, legal reviews

You cannot enforce “team X only edits namespace Y” with permissions alone — permissions are project-wide — but the namespace boundary makes the hand-off obvious and keeps imports/exports clean.

Creating and managing namespaces

1. Open the project and go to the namespace selector on the Translations page
2. Click Add Namespace
3. Name it in lowercase, short, hyphen-separated if needed (user-settings, not UserSettings)
4. Optionally add a description

You can rename and delete namespaces from the same place.

Caution

Deleting a namespace deletes every key and value inside it. If you need a safety net, export the namespace first.

The default namespace cannot be deleted — if you want it renamed in URLs, create a new namespace, move keys into it, and stop using default.

Moving keys between namespaces

Select keys in the Translations page → Move namespace → pick the target. Values, history, and comments move with them. If a key name collides with an existing key in the target namespace, the move fails and tells you which key to rename first.

Note

After moving, consumer apps that hard-coded the old namespace will stop finding those keys. Update loader configs or build-time pulls before republishing.

Best practices

• Start at one, split when it hurts. Don’t design namespaces upfront.
• Keep a common namespace for strings that appear everywhere — it’s the one every page loads.
• Aim for 3–15 namespaces. Hundreds of namespaces recreates the problem you tried to solve.
• Use stable, URL-safe names. They end up in CDN URLs and build pipelines — renaming is cheap but breaks consumers until they redeploy.

Limits

• Keys are unique per namespace; the same key name can legitimately exist in multiple namespaces.
• Permissions are not namespace-scoped — for strict editorial boundaries, split into separate projects.

Troubleshooting

An app is missing keys after I moved them

Check that the consumer is loading the new namespace. Build-time pulls need a republish; runtime loaders need their namespace list updated.

I see two keys with the same name

They are in different namespaces. Use the namespace column in the Translations page to tell them apart.

Related

Translations Edit keys and values inside a namespace.

CDN Deployment How namespaces map to CDN URLs and what the status filter does.

Import & Export Import or export one namespace at a time.

Consume Translations Load only the namespaces a screen needs.