Appearance
Translations, key by key
A site in several languages keeps each document once, in its own language (the original). Beside it sits a translation for each other language, and a translation holds only the words. A photograph, a price or a date is the original's in every language, so changing it once changes it everywhere. This is contract 3. On the older contract 2, each language was a full copy of every document (below).
This page is the format: which values a translation holds, how they are named, what a record says, and what is refused. How to lay a site out in several languages and work on it, and when to add a language at all (only when the brief names one), is the guide.
Declaring the languages
The schema says them: locale, required, is the site's own language, and locales are the others (the schema). On the scaffold they are LOCALE and LOCALES in src/content/blocks.ts. npx @jtakeit/astro create <slug> --locale de-CH --locales en lays out a translation beside every original. It also writes the words that are not content — the form's messages, the pager — in src/copy/<locale>.ts.
A language is spelt in canonical BCP 47, de-CH, in the schema, in file names and in data. An address carries its lowercase form, with the language in front: /preise in the site's own language, /en/preise and /fr-ch/preise in the others. A collection's route may give its words per language, {"de": "/werke/{slug}", "en": "/works/{slug}"}, and the language's prefix still goes in front: /en/works/oak. An entry's translation may give the entry a slug of its own.
The file
A translation is <name>.<locale>.json beside its original:
| original | its English |
|---|---|
jtk/pages/index.json | jtk/pages/index.en.json |
jtk/pages/preise.json | jtk/pages/preise.en.json |
jtk/entries/works/eiche.json | jtk/entries/works/eiche.en.json |
jtk/shared.json | jtk/shared.en.json |
jtk/modules/<module>.json | jtk/modules/<module>.en.json, only where the module's settings have words — the bookings' have none |
Its keys come in this order: of, locale, name or slug, visible, seo, fields, blocks, translated.
ofis the original'sid. The shared text and a module's settings have no id and carry noof, because the file beside them names them.localeis the translation's language, and it is required. It is one of the schema'slocales. There is one translation of a document per language.- What a page's translation holds:
name,seo, and the words of its blocks, each block named by the original's_key, with notypeand nov. A page's blocks are the developer's structure, so the original has them and the translation has only their words. - What an entry's translation holds:
slug,seo, the words of itsfields, its bodyblockswhole, andvisible: falseto hold the entry back in that language. - What the shared text's translation holds: the words of its blocks, by
_key.
A page, from the platform's corpus (backend/api/sites/testdata/overlays/page-words-laid-by-key.json). The original, jtk/pages/preise.json, has a hero with a title, a lead, a photograph and a link, and a price list of two rows. Its English is this:
json
{
"of": "0193a5c2-7f4e-7c1a-9b2e-5d1f0c3a8e21",
"locale": "en",
"name": "Prices",
"blocks": [
{ "_key": "hero", "title": "Our prices", "image": { "alt": "The salon" } }
]
}Served in English, the hero says «Our prices» over the original's photograph, with the same file and focus, and the English alt. Everything this file leaves out is the original's German. The lead, the list's title and its rows are listed as fromBase, so the page gives them lang="de-CH".
A picture's words are the translation's in its language, the original's where it gives none, and — where the original's field says none either — the words its file has in the site's media library, which a picture placed from the library starts from (the panel). The file's words are written into the original's value when the picture is placed, and given anew to every place still saying them when they change; a translation's words are never touched by them.
An entry (entry-words.json), whose original jtk/entries/works/eiche.json has a title, an excerpt, a date, a price, a cover, a gallery of two pictures (p1, p2) and a body:
json
{
"of": "0193a5c3-1b2a-7e44-8a10-6c2f9d3e4b55",
"locale": "en",
"slug": "oak",
"seo": { "title": "Oak" },
"fields": {
"title": "Oak",
"cover": { "alt": "The oak door" },
"pictures": [ { "_key": "p2", "alt": "The handle" } ]
}
}In English the entry is at its own slug, /en/works/oak. Its date, price and pictures are the original's, with the English words laid over them by key. What nobody translated stays in the original's words and is said as such: fields.excerpt, fields.pictures[p1].alt and blocks, the body.
Which values are per language
The kind decides, by one rule that the import, the save, the build, the kit's door and the counts all share. A field may say otherwise with localized (field kinds has the column):
| a field of the kind | in a translation |
|---|---|
text, textarea, richtext_lite, markdown | its whole value |
media, one picture | its alt; the file, the focus and the poster are the original's |
media, a gallery | each picture's alt, by the picture's _key; the pictures and their order are the original's |
list | the words in its rows, by each row's _key; the rows and their order are the original's |
url | nothing: the original's link |
number, money, duration, time_of_day, date, bool, select, ref, tel, email, sku, picks | nothing: one value in every language |
localized: trueon a picture, a gallery, a link or a list makes the whole value per language. Use it for a photograph with words on it, a link to a page in that language, or a list each language has its own of.localized: falseon a text makes it one value: a name nobody translates, a street, a postcode.localizedon any other kind is refused withJTK_E_ATTRIBUTE_INVALID.- An entry's body (
blocks) is whole per language. A translation withblocksof its own replaces the original's, so a German post may have a paragraph the English one has not. A translation withoutblocksshows the original's. - A page's
name, the text fields ofseo, and an entry'sslugare per language. A slug left as the original's is never counted as untranslated.
A value that is the same in every language, written into a translation, is refused with JTK_E_TRANSLATION_SHARED. This, from refused-shared-value-price.json, sets a price for English alone:
json
{
"of": "0193a5c2-7f4e-7c1a-9b2e-5d1f0c3a8e21",
"locale": "en",
"blocks": [
{ "_key": "list", "items": [ { "_key": "r1", "title": "Haircut", "price": { "minor": 5000 } } ] }
]
}Change the price in the original instead, and every language has it.
Paths
A value's place in a translation is named by keys, never by position. The same names key translated, the counts get_site gives, and fromBase:
| path | the value |
|---|---|
name | a page's name |
slug | an entry's slug in the language |
seo.title | a field of seo |
blocks[hero].title | a field of a page's block |
blocks[hero].image.alt | a picture's words |
blocks[list].items[r7k2].title | a field of a row |
fields.title | an entry's own value |
fields.pictures[g1].alt | a gallery picture's words, in an entry |
blocks | an entry's body, one value whole per language |
settings.<key> | a word of a module's settings |
translated: what each value was made from
A translation may say, for each value it gives, what that value was translated from: a record under the value's path, with exactly three keys.
fromis the first eight hex digits of the SHA-256 of the original value's canonical JSON. Canonical means every object's keys in byte order at every depth, no spaces, and strings escaped asJSON.stringifyescapes them."Hallo"is09d941a5:printf '%s' '"Hallo"' | shasum -a 256 | cut -c1-8.byisperson,agentormachine. An agent writes its own words and nevermachine: the machine (DeepL) is a panel action for a person, off on a deployment without a key, and no tool reaches it (machine translation).atis a moment in RFC 3339.
A record that is anything else is refused with JTK_E_TRANSLATION_RECORD.
From outdated-by-digest.json: the original home page's hero says "title": "Hallo" and "lead": "Seit 1998 an der Langstrasse", and its English is this:
json
{
"of": "0193a5c2-7f4e-7c1a-9b2e-5d1f0c3a8e21",
"locale": "en",
"name": "Home",
"blocks": [ { "_key": "hero", "title": "Hello", "lead": "Since 1998" } ],
"translated": {
"blocks[hero].title": { "from": "09d941a5", "by": "agent", "at": "2026-11-10T09:00:00Z" },
"blocks[hero].lead": { "from": "64cba83f", "by": "person", "at": "2026-11-10T09:00:00Z" }
}
}09d941a5 is the digest of "Hallo", the title as it stands, so the title is current. 64cba83f is the digest of "Seit 1998", the lead before it grew, so the lead is outdated.
Leave translated out, which is the ordinary case. The import records each value the translation gives as made from the original as it stands, by the agent. It also keeps the record it wrote for a value you did not change, which is how an outdated value stays outdated until it is translated again. Write a record yourself only to say who made a value, and then use the digest the platform wrote.
A record is never made from nothing. A value the translation gives where the original has none, such as SEO on a page whose original has no SEO, is the translation's own. It has no record, and it is neither missing nor outdated. A record whose from is empty counts as no record: nothing refuses it, and it is never written back. If the original later gains a value, the next import records the translation's value as made from it.
Where a translation stands
Each per-language value of a document is in one of these states:
| state | means | the site shows |
|---|---|---|
| missing | nobody translated it | the original's words, marked with the original's lang — or, where the collection says untranslated: "hide", no entry in that language at all |
| current | made from the original as it is now | the translation |
| outdated | the original changed since: from is not its digest | the older translation, which still beats the original's language |
| machine | a person had the machine draft it in the panel (by: machine), and nobody has pressed Checked yet | the translation, once a version with it is published; the panel marks it machine, unchecked |
get_site adds them up per language — fr-CH: 6 to translate, 2 outdated — with each document's translation file and the paths, so you can do the work from the answer. The count is the draft's, which your checkout has after a save. A picture's alt counts; a slug left as the original's does not.
A language without a translation
What a language with no translation of an entry does is its collection's untranslated:
base, the default: the entry is there in the original's words, and the kit's door gives them the original'slang.hide: the entry is hidden in that language. It is built for the panel's preview, listed nowhere and in no sitemap. A translation withvisible: falseholds one entry back the same way.
A page and the shared text always fall back to the original's words. hreflang and the sitemap name a language only where a translation exists.
What is booked is in every language
An entry of a collection a module names in one of its roles — the bookings' services, resources and classes — is booked by the diary in any language's form, and the diary reads the original. So such an entry is never missing from a language. Where nobody translated it, it shows the original's words.
- The collection may not say
untranslated: "hide", which is refused withJTK_E_ATTRIBUTE_INVALID. - A translation of its entry may not say
visible: false, which is refused withJTK_E_DOCUMENT_INVALID. This, frombooked-entry-held-back-refused.json, tries to hold a master back in English:
json
{
"of": "0193a5c3-0a11-7d02-9f3c-1e2d3c4b5a72",
"locale": "en",
"visible": false,
"fields": { "bio": "Cutting since 2010." }
}The panel offers no switch for it either, and the site serves such an entry in every language regardless. The booking form names a service and a master by the original's slug, which the diary books by.
What is refused, and what is advice
validate_schema judges translations before the push: by site and ref, or with the tree sent as text beside the schema. npx @jtakeit/astro schema does the same, and so does the import. The build stops on a translation the import would refuse.
| code | when |
|---|---|
JTK_E_TRANSLATION_SHARED | a translation holds a value that is the same in every language |
JTK_E_TRANSLATION_RECORD | a record in translated is not {from, by, at} as above |
JTK_E_DOCUMENT_INVALID | a key a translation has not got, a block, row or picture without its _key, a type on a page's block, a language the schema does not list, two translations of one document in one language, an address two entries would share in a language, or visible: false on an entry a module books |
JTK_E_ATTRIBUTE_INVALID | localized on a kind with no words, untranslated that is neither base nor hide, or hide on a collection a module books |
JTK_W_TRANSLATION_ORPHAN | advice: words for a block, a row or a picture whose _key the original has not got |
JTK_E_MACHINE_OFF, JTK_E_MACHINE_ALLOWANCE | the panel's machine translation, refused to a person: no DeepL key here, or the site's allowance spent. Never an agent's: translate in the files |
An orphan's words are shown nowhere, and the next save leaves them out of the file, while the history keeps them. Here (unknown-key-is-advice.json), the original has no row gone and no block old, so both are advised against and the row r2 is translated:
json
{
"of": "0193a5c2-7f4e-7c1a-9b2e-5d1f0c3a8e21",
"locale": "en",
"name": "Prices",
"blocks": [
{ "_key": "list", "title": "Cuts", "items": [ { "_key": "gone", "title": "Perm" }, { "_key": "r2", "title": "Colour" } ] },
{ "_key": "old", "title": "A block removed" }
]
}Contract 2, the older contract
A site not yet moved keeps a full copy of every document per language: a page at jtk/content/<locale>/<path>.json, saying "locale": "<locale>", at the same address with the language in front. Nothing ties a photograph or a price across the copies. jtk upgrade contract-3 turns each copy into a translation beside its original. A value that differs between copies, such as two photographs or two prices, stops the move and is listed for a person to answer: --take-base keeps the original's, and localized: true on the field keeps each language's own.