String sync and integration keys

A continuous project fills up with strings in three ways: your code syncs them (SDK, CLI, or API), you upload a JSON file in the hub, or one of the site integrations reports them from your live site. However they arrive, strings are processed the same way — this page explains that path and how to handle the keys that authorize it.

Upload strings from the hub

With the developer integration mode selected, the hub’s Integration tab has an Upload Translations card. Drop a JSON file (or browse for one) and the hub parses it before anything is sent: you see each namespace and how many keys it contains. Flat files, nested objects, and multi-namespace files all work. Click Sync Translations to send the namespaces one by one, with per- namespace progress, and get a summary of keys added and updated.

Syncing from code works the same way through the API — see the developer quickstart and recipes.

How a sync is processed

• Asynchronous. A sync is accepted immediately and processed in the background as a job whose status can be tracked. The hub tracks it for you; from the API you poll the job until it completes.
• Grouped by namespace. Strings belong to a namespace (default unless you set one), and nested JSON is flattened to dot-notation keys — a value at menu.header.title is stored under that key and rebuilt into the same nested shape when your app fetches translations.
• Format-aware. ICU MessageFormat is understood: placeholders like {name} are protected through translation, and plural or select messages ({count, plural, ...}) are handled per branch so every form gets translated.
• Idempotent. A key maps to one stable string in the project. Re-syncing the same content updates it in place — running the same sync twice never creates duplicates, so it is always safe to re-run.
• Auto-translated. New or changed source strings mark the affected target languages as pending, and the translation pipeline picks them up automatically — with your project’s translation memories, glossaries, and MT settings, like any other content.
• Resilient. Transient failures are retried automatically with increasing delays. A job that keeps failing is set aside rather than silently dropped, and because syncs are idempotent, simply re-running the sync from your side is a safe recovery too.

Monthly token limit

A continuous project can carry a cap on billable translation tokens per month. Set it when creating the project or later in the hub’s Settings tab; leave it empty for no limit. When the cap is reached, machine translation stops for the current month — your strings are still accepted and stored, they just wait.

Managing integration keys

Keys live in the project hub under Settings → API Keys. Each key is scoped to one project and one source language; it cannot touch anything else.

Type	Prefix	Can do	Where it belongs
Publishable	pk_	Read translations, sync source strings	Client-side code: the JS snippet, the edge proxy, anything a visitor can see
Master	sk_	Everything publishable keys can, plus writing translated text back through the API	Server-side only — environment variables, CI secrets

Create

Click + Create Key, describe where the key will live (for example “Production web app”), and pick the type. The description is how you’ll recognize the key later, so name it after the system that uses it, not the person who made it.

Pause and reactivate

The toggle pauses a key without deleting it. Requests with a paused key fail immediately; flip it back and the same key works again. Pausing is the right tool when you’re diagnosing unexpected traffic or taking an environment offline temporarily.

Revoke

Deleting a key is permanent and cannot be undone. Any integration still configured with it stops working at once.

Practices worth keeping

• One key per environment. Give production, staging, and local development their own keys so you can pause or revoke one without touching the others.
• Publishable keys in anything shipped. If the key ends up in a browser, an app bundle, or a public repository, it must be a pk_ key.
• Rotate without downtime. Create the new key, deploy it everywhere, then delete the old one — never the other way around.
• Pause before you delete. If you’re not sure whether a key is still in use, pause it and watch for breakage; deletion can’t be taken back.