Skip to content

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:

originalits English
jtk/pages/index.jsonjtk/pages/index.en.json
jtk/pages/preise.jsonjtk/pages/preise.en.json
jtk/entries/works/eiche.jsonjtk/entries/works/eiche.en.json
jtk/shared.jsonjtk/shared.en.json
jtk/modules/<module>.jsonjtk/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.

  • of is the original's id. The shared text and a module's settings have no id and carry no of, because the file beside them names them.
  • locale is the translation's language, and it is required. It is one of the schema's locales. 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 no type and no v. 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 its fields, its body blocks whole, and visible: false to 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 kindin a translation
text, textarea, richtext_lite, markdownits whole value
media, one pictureits alt; the file, the focus and the poster are the original's
media, a galleryeach picture's alt, by the picture's _key; the pictures and their order are the original's
listthe words in its rows, by each row's _key; the rows and their order are the original's
urlnothing: the original's link
number, money, duration, time_of_day, date, bool, select, ref, tel, email, sku, picksnothing: one value in every language
  • localized: true on 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: false on a text makes it one value: a name nobody translates, a street, a postcode.
  • localized on any other kind is refused with JTK_E_ATTRIBUTE_INVALID.
  • An entry's body (blocks) is whole per language. A translation with blocks of its own replaces the original's, so a German post may have a paragraph the English one has not. A translation without blocks shows the original's.
  • A page's name, the text fields of seo, and an entry's slug are 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:

paththe value
namea page's name
slugan entry's slug in the language
seo.titlea field of seo
blocks[hero].titlea field of a page's block
blocks[hero].image.alta picture's words
blocks[list].items[r7k2].titlea field of a row
fields.titlean entry's own value
fields.pictures[g1].alta gallery picture's words, in an entry
blocksan 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.

  • from is 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 as JSON.stringify escapes them. "Hallo" is 09d941a5: printf '%s' '"Hallo"' | shasum -a 256 | cut -c1-8.
  • by is person, agent or machine. An agent writes its own words and never machine: the machine (DeepL) is a panel action for a person, off on a deployment without a key, and no tool reaches it (machine translation).
  • at is 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:

statemeansthe site shows
missingnobody translated itthe original's words, marked with the original's lang — or, where the collection says untranslated: "hide", no entry in that language at all
currentmade from the original as it is nowthe translation
outdatedthe original changed since: from is not its digestthe older translation, which still beats the original's language
machinea person had the machine draft it in the panel (by: machine), and nobody has pressed Checked yetthe 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's lang.
  • hide: the entry is hidden in that language. It is built for the panel's preview, listed nowhere and in no sitemap. A translation with visible: false holds 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 with JTK_E_ATTRIBUTE_INVALID.
  • A translation of its entry may not say visible: false, which is refused with JTK_E_DOCUMENT_INVALID. This, from booked-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.

codewhen
JTK_E_TRANSLATION_SHAREDa translation holds a value that is the same in every language
JTK_E_TRANSLATION_RECORDa record in translated is not {from, by, at} as above
JTK_E_DOCUMENT_INVALIDa 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_INVALIDlocalized on a kind with no words, untranslated that is neither base nor hide, or hide on a collection a module books
JTK_W_TRANSLATION_ORPHANadvice: words for a block, a row or a picture whose _key the original has not got
JTK_E_MACHINE_OFF, JTK_E_MACHINE_ALLOWANCEthe 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.