The CDN
How transglot serves published translations to your app at runtime: the addresses, how they cache, and the key that reads them.
The CDN serves the versions you publish over plain HTTPS, so your app can load translations at runtime and a corrected string reaches production without a new build. It only ever serves published versions. Work in progress in the editor is never reachable through it.
Runtime delivery is included on Starter and above. Owners and Admins manage it from Settings → Developer → Runtime delivery (CDN).
Latest and versioned addresses
Every published language has two addresses on the API host:
https://api.transglot.ai/v1/cdn/{project-id}/{locale} # latest
https://api.transglot.ai/v1/cdn/{project-id}/{locale}/v{n} # one version{project-id} is the project's numeric id. You do not need to look it up: Settings → Developer → Runtime delivery (CDN) shows each language's Latest URL, and its Immutable URL once it has been published, ready to copy.
- The latest address always serves the newest published version of that language. Point your app here when you want every publish to reach users without a deploy.
- A versioned address serves exactly that version, forever. Point your app here when you want to control when a change goes live, or to roll back to an earlier version.
transglot keeps the 20 most recent versions of each language. A versioned address older than that returns 404.
Caching
| Address | Cache-Control | What it means for you |
|---|---|---|
| Latest | public, max-age=60, must-revalidate | A cache may serve the previous version for up to a minute after a publish, then checks again. |
| Versioned | public, max-age=31536000, immutable | Cached for a year and never rechecked, because its content can never change. |
Every response carries an ETag. A client or cache that sends it back in If-None-Match gets an empty 304 Not Modified when nothing has changed, so revalidating the latest address is cheap. Responses also carry X-Cdn-Version (the version served) and X-Cdn-Format (its file format).
Published versions are public content meant to be fetched from any app, so responses allow every origin (Access-Control-Allow-Origin: *).
Requests are rate limited per key and IP address. Let a CDN of your own, or the runtime SDK's cache, absorb repeat reads instead of fetching on every page view.
CDN keys
Every request needs a CDN key for the project. It is the narrowest credential transglot issues: it reads this project's published versions and nothing else, and it cannot change anything. Send it in the X-Transglot-Cdn-Key header, or as a ?key= query parameter where you cannot set headers.
curl https://api.transglot.ai/v1/cdn/42/de \
-H "X-Transglot-Cdn-Key: taicdn_..."A CDN key is not a deploy token. Deploy tokens are secrets that push and pull strings; a CDN key only reads what you already chose to publish.
Create a key
Open the delivery settings
Open the project's Settings → Developer and scroll to Runtime delivery (CDN).
Name the key
Under CDN keys, enter a Name that says where the key is used, such as the CDN or app that will hold it.
Create and copy it
Select New CDN key. The key is shown once, in Your new CDN key: copy it before you close the dialog. It is stored hashed and cannot be shown again; if you lose it, create another.
Delete a key
Select Delete next to the key and type its name to confirm. Anything still fetching with that key gets 401 straight away, including caches you do not control, so roll out a replacement first if the key serves production.
Delivery settings
Two settings in Runtime delivery (CDN) apply to every language in the project. Change them, then select Save settings.
| Setting | Options |
|---|---|
| Freshness | Manual: publish explicitly (the default): a version is made only when someone publishes. Auto: publish on every push: each push publishes the language it uploaded. |
| Delivery format | Project default, which follows the format your project last pushed (or flat JSON if it has never pushed), or a specific format. |
A version is published in one format. A new format applies from each language's next publish. The runtime SDKs read the JSON formats (json_flat, json_nested, laravel_json, flutter_arb); see the SDKs.
You can ask for a specific format with ?format=. If it is not the format the version was published in, the CDN returns 404 rather than converting it.
Errors
Errors are JSON problem responses. The type field names the problem, for example /problems/cdn-key-invalid.
| Status | Slug | Cause |
|---|---|---|
401 | cdn-key-required | No key in the header or the query string. |
401 | cdn-key-invalid | The key does not exist or was deleted. |
404 | not-found | The project id is not the key's project, or the language is not in the project. |
404 | not-published | The language has never been published, the version is older than the 20 kept, or the requested format is not the published one. |
403 | plan-feature-required | The account's plan no longer includes runtime delivery. Your keys are kept and work again after an upgrade. |
403 | workspace-closed | The workspace has been closed, so its published versions are no longer served. |
The 403 responses are sent with Cache-Control: no-store, so a cache in front of the CDN never keeps them.