Runtime SDKs
How your app reads published translations from the transglot CDN at runtime, and which package to use for your framework.
The runtime SDKs load your published translations over HTTP while your app runs, so a fixed typo or a new language reaches users without a new build. Every package reads the same CDN endpoint and builds on one client, @transglot/runtime.
How runtime delivery works
You publish a locale
Publishing freezes a locale's current translations into a numbered version. You publish from the project's Deploy screen, from Publish now on the Runtime delivery (CDN) card, or from your pipeline. With Freshness set to Auto: publish on every push, every push publishes. See Publish a locale.
A published bundle holds only the keys that have a translation in that locale, in the project's delivery format.
The CDN serves it
Each published locale has two addresses on https://api.transglot.ai:
| Address | Serves | Cache headers |
|---|---|---|
/v1/cdn/{project}/{locale} | The latest published version | public, a short max-age, must-revalidate, and an ETag |
/v1/cdn/{project}/{locale}/v{n} | Version n, which never changes | public, one year, immutable |
The latest address is the one to use. Its short lifetime means a new publish reaches users within about a minute, and revalidating it is cheap: send the ETag back in If-None-Match and an unchanged bundle answers 304 Not Modified with no body. A version address suits pinning during a rollout. transglot keeps a limited number of recent versions per locale, so an old version address eventually stops resolving.
Your app reads it with a CDN key
Every read needs the project's CDN key, in the X-Transglot-Cdn-Key header or the key query parameter. A CDN key is read-only, belongs to one project, and reaches only that project's published bundles, never unpublished translations or another project's content.
Get a CDN key
Runtime delivery is available on the Starter plan and above.
- Open the project's Settings → Developer.
- In the Runtime delivery (CDN) card, under CDN keys, enter a Name (for example, the app or edge that will use it).
- Select New CDN key, then Copy. The key starts with
taicdn_. transglot stores only a hash, so it is shown once; if you lose it, create another.
To revoke a key, select Delete next to it. Anything still using it starts receiving 401 responses immediately, including caches you do not control, so roll out its replacement first.
The same card shows each locale's Latest URL. The number after /v1/cdn/ is the project id the SDKs ask for.
Choose a package
| Package | Use it for | Server rendering |
|---|---|---|
@transglot/runtime | Any JavaScript runtime: browsers, Node.js 20+, React Native, workers | You call it |
@transglot/react-i18n | React 18 and 19 | No, loads after mount |
@transglot/next | Next.js 14 and 15, App Router and Pages Router | Yes |
@transglot/vue | Vue 3.3 and later | No |
@transglot/svelte | Svelte 5 | No |
@transglot/sveltekit | SvelteKit 2 | Yes |
@transglot/angular | Angular 17 and later | No |
@transglot/solid | SolidJS 1.6 and later | No |
@transglot/astro | Astro 4 and 5, with React islands | Yes |
@transglot/i18next-backend | Apps already on i18next or react-i18next | Through i18next |
@transglot/react-intl | Apps already on react-intl (FormatJS), and full ICU MessageFormat | You call it |
@transglot/pseudo | Generating a pseudo-locale for testing; does not read the CDN |
@transglot/react is not a runtime SDK: it adds the in-context editor for reviewers. See the in-context editor.
Delivery formats
The SDKs read the JSON-family delivery formats: json_flat, json_nested, laravel_json and flutter_arb. Choose one in Delivery format on the Runtime delivery (CDN) card; Project default follows the format you last pushed. Plural keys are published only in flutter_arb, as ICU plural messages; the other three leave them out. The JavaScript runtime page has the details.
Things that apply to every package
- Missing keys. Looking up a key that is not in the bundle returns the key, or for the interop packages whatever i18next or react-intl do. No package falls back to another locale on its own.
- Browsers. The CDN sends
Access-Control-Allow-Origin: *on bundles but does not answer CORS preflight requests. In a browser, passauthIn: 'query', and read In a browser for what that means for revalidation and errors. Server-side loading is not affected. - Keys in client code. A CDN key in a browser bundle is visible to anyone, and it can read only what you have published for that project. The server-rendering packages keep the key on the server unless you opt into browser-side loading.
- Rate limits. CDN reads are rate-limited per key and client address. On
429, the SDKs wait forRetry-Afterand retry twice before failing withrate-limited. A server that renders every request should cache bundles rather than fetch one per request. - Errors. Every package reports failures as
RuntimeErrorwith a stableslug. See Errors.
Without an SDK
The CDN is plain HTTP, so any language can read it:
curl -i \
-H "X-Transglot-Cdn-Key: taicdn_your_key" \
https://api.transglot.ai/v1/cdn/42/frThe body is the bundle in the project's delivery format, with a matching Content-Type. The response also carries ETag, X-Cdn-Version (the published version number) and X-Cdn-Format (the format identifier). Add ?format=<identifier> to assert a format: if the version was published in a different one, the response is 404 with the problem type not-published, and an unknown identifier is 422 invalid-format. Errors are application/problem+json documents whose type is /problems/<slug>.