Staging → Production Publishing

Translations ship to the CDN on approval. That’s great for speed but dangerous when your app’s staging and production environments share a project: a translator’s draft-in-progress can appear in production minutes after approval. This recipe covers two clean ways to separate environments.

Two approaches

Approach	Best for	Isolation
Two projects — my-app + my-app-staging	Fully independent review and QA per environment	Strong — no cross-environment leakage
Status-gated single project	Small teams, low-risk copy changes	Moderate — relies on discipline

Pick one and commit. Mixing them creates confusion.

Approach A — Two projects

One project is production, another is staging. Each has its own API keys, CDN distribution, and language set. Translations flow from staging to production by export/import.

Setup

1. Create two projects — e.g., checkout (prod) and checkout-staging. Same source language.

2. Point staging app to the staging CDN — staging .env:

   COMVI_CDN_URL=https://cdn.comvi.io/<staging-distribution-token>

   Production .env points at the prod distribution.

3. Work in staging first — translators create keys, review, publish. The staging app picks up changes automatically.

4. Promote to production on your release cadence

   Export from staging, import to production. Use the Import/Export flow with the “only translated” filter so drafts don’t promote.

   # Pull staging
   COMVI_API_KEY=$STAGING_KEY npx comvi pull --path ./dump
   # Push to production
   COMVI_API_KEY=$PROD_KEY npx comvi push --path ./dump --force-mode keep

5. Automate the promotion in CI

   On every release tag, run the promotion script. See CI/CD Integration.

Trade-offs

Pro: A draft in staging cannot reach production no matter what — they are physically separate distributions.

Con: Two projects to maintain. Glossaries and TM need to be organization-level (they already are) to share across. Members need access to both. Billing may count both.

Tip

If your production environment is critical and you’ve been burned by draft copy going live, use two projects. The maintenance overhead is worth the isolation.

Approach B — Status-gated single project

One project. Translators work in the editor; staging reads Not reviewed + Translated, production reads only Translated.

Setup

1. Create two API keys (or two CDN configs — see CDN Deployment).

2. Configure two CDN distributions in the project

   • Staging distribution — status filter includes Not reviewed and Translated.
   • Production distribution — status filter is Translated only.

3. Point apps at their respective distributions

   Staging .env:

   COMVI_CDN_URL=https://cdn.comvi.io/<staging-distribution-token>

   Production .env:

   COMVI_CDN_URL=https://cdn.comvi.io/<prod-distribution-token>

4. Review discipline is the gate

   A draft reaches production the moment a reviewer sets Translated. Make sure reviewers understand this — the “preview” is staging with Not reviewed included.

Trade-offs

Pro: One project to maintain. Drafts are previewable in staging automatically — no export/import dance.

Con: Approving in the editor ships. If your team needs a “staged-for-one-week-then-go-live” pipeline, this approach doesn’t give you that gap.

Testing new strings in staging

Regardless of approach, the same pattern works:

1. Developer adds a new key in code (e.g., checkout.new_promo_banner).
2. Developer pushes the key to Comvi (CLI or API).
3. Translators fill it in.
4. Staging picks it up; QA verifies the banner in the staging app.
5. Reviewer approves → production sees it on next deploy cycle.

Note

If your key disappears from staging but shows on production, check that your staging API key has the read scopes it needs and that the staging CDN is configured to include Not reviewed drafts.

Rollback

Publish is auto, but rollback is manual (no one-click rollback in Comvi — see CDN Deployment):

• Approach A — Re-import the previous export into the prod project, republish.
• Approach B — Edit the offending value in the editor, re-approve, let auto-deploy pick it up.

Keep regular exports as your source of truth for rollback points. Schedule comvi pull daily as a backup.

What to avoid

• Same distribution for staging and production. A translator approving a bad string ships it everywhere.
• Sharing one API key across environments. Rotate/revoke on prod becomes impossible without breaking staging.
• Promoting drafts by accident — in Approach A, always use the status filter on export/import.

Related

CDN Deployment Status filters, debounce, failure thresholds.

Import & Export The promotion mechanism in Approach A.

Translator + Reviewer Workflow The review gate that status filtering relies on.

CI/CD Integration Automate promotion on release.