Appearance
A site in several languages
How an agent writes a site in more than one language on contract 3: one document in the site's own language — the original — and, beside it, a translation that holds only the words. The owner edits the languages as one in the panel (the panel · languages); you write them in the files.
Only when the brief names it. A second language is a second site to keep written, every page and every post, for ever (the brief).
Laying it out
npx @jtakeit/astro create <dir> --locale de-CH --locales en--locale is the original's language, --locales the others. They become the schema's locale and locales, spelt as BCP 47 tags (de-CH) in the schema, in file names and in the data; an address carries the lowercase form in front of it — /preise, /en/preise, /fr-ch/preise — and the kit's door is the one place that maps between them. A language added later is a line in LOCALES (src/content/blocks.ts), then npx @jtakeit/astro copy <locale> and npx @jtakeit/astro schema.
npx @jtakeit/astro copy <locale> writes src/copy/<locale>.ts: the words that are not content — the form's messages, the privacy page, a listing's pager — in the kit's words. A language without one says the site's own words there, marked with their lang.
The files
A translation is <name>.<locale>.json beside its original:
jtk/pages/preise.json the page, in the site's own language
jtk/pages/preise.en.json its English
jtk/entries/blog/erster.json
jtk/entries/blog/erster.en.json
jtk/shared.json, jtk/shared.en.jsonIt says which document it translates — of, the original's id — and its locale, and then only the words, every block, row and picture named by the original's _key, never by its place. It carries no type and no v; those are the original's.
json
{
"of": "0193a5c2-7f4e-7c1a-9b2e-5d1f0c3a8e21",
"locale": "en",
"name": "Prices",
"seo": { "title": "Prices" },
"blocks": [
{ "_key": "hero", "title": "Our prices", "image": { "alt": "The salon" } },
{ "_key": "list", "items": [ { "_key": "r7k2", "title": "Haircut" } ] }
]
}- A page's translation holds its
name, itsseoand the words of its blocks. The blocks themselves are the original's: a block added, moved or removed there is added, moved or removed in every language. - An entry's translation holds its
slug(its address in that language, where you give one),seo, the words of itsfields, andblocks— an entry's body is whole per language: a translation withblocksof its own replaces the original's, one without shows the original's. - The shared text's translation (
jtk/shared.en.json) holds the words of its blocks, and noof: the file beside it names it. So would a module's settings, where a module says a field islocalized; the bookings and the shop have nothing to translate.
Which values are words
The field's kind decides, unless the field says localized:
| per language | the same in every language |
|---|---|
text, textarea, rich text, markdown; a picture's alt; a gallery's words, per picture by _key; a list's words, per row by _key; name, seo, a slug | a picture's file, focus and poster; a price, a number, a date, a choice, a reference, a phone, an email, a link |
A picture with words on it, a link to a page in that language, or a list each language has its own of says localized: true, and is then whole per language; a name that is never translated says localized: false. A shared value in a translation is refused — JTK_E_TRANSLATION_SHARED: change it in the original, and every language has it.
The record of what a translation was made from
Each value a translation gives may carry a record in translated, under the value's path — name, slug, seo.title, blocks[hero].title, blocks[list].items[r7k2].title, fields.title, fields.pictures[g1].alt, blocks for an entry's body:
json
"translated": {
"blocks[hero].title": { "from": "9f2c41d0", "by": "agent", "at": "2026-11-12T09:00:00Z" }
}from is the first eight hex digits of the SHA-256 of the original value's canonical JSON, by is person, agent or machine, at a moment.
- Leave the record out for a value you write or change. The import records it as made from the original as it stands now, by the agent.
- Keep the record the platform wrote for a value you leave as it is: that is how a value made from an older original stays outdated until somebody translates it again.
- A record is never made from nothing. Words where the original has none — a page with no SEO whose English gives some — are the translation's own: no record, neither missing nor outdated. A record whose
fromis empty is no record. - A malformed record —
fromnot eight hex digits,bynot one of the three, a stray key — is refused,JTK_E_TRANSLATION_RECORD. Leave it out. - Words for a block, a row or a picture the original has not got — removed there, or a key misspelt — are advice,
JTK_W_TRANSLATION_ORPHAN: shown nowhere, and left out by the next save.
What nobody translated
A language without a translation of a value shows the original's words, and says so: the door hands out which values came from the original (fromBase, lang()), and the page gives them the original's lang. hreflang and the sitemap name a language only where a translation is.
- A collection may hide instead:
untranslated: "hide"keeps an entry out of a language nobody translated it into. - An entry may be held back in one language:
"visible": falsein its translation. - What a module books is in every language, always. An entry of a collection the bookings name — the services, the masters, the classes, the cars — is booked by the diary in any language's form, so it is never missing from one. Its collection may not say
untranslated: "hide"(JTK_E_ATTRIBUTE_INVALID), and its translation may not say"visible": false(JTK_E_DOCUMENT_INVALID). Untranslated, it shows the original's words. The form names a service and a master by the original's slug (entry.baseSlug), whatever a language calls it. - What a shop sells is in every language too. A product the page's language has no translation of is priced and sold all the same, in the site's own words: the language chooses the words, never what is sold, and a price, a SKU and a variant's
picksare the original's. The page sends itslocalewith the cart and the checkout, the order's lines are frozen in it, and the buyer's letters speak the order's language — the confirmation, on its way, ready for pick-up — in the language the page named where the platform's letters speak it (fr-CHis French) and in the site's own otherwise; the owner's letter stays in the site's language (the buyer's language). A shipping method's name is the site's own words in every language.
What is left to do
get_site says it, for a site in several languages, in languages: a line a language — en: complete, fr-CH: 6 to translate, 2 outdated — and each document with its translation's file and the paths still missing (the original's words shown untranslated) or outdated (made from an original that has changed since). An agent told 6 to translate writes those six. It counts the panel's draft, so pull first (git pull, or pull_code and jtk pull): the owner may have translated some meanwhile. A slug left as the original's is not counted; a picture's alt is.
jtkit progress says the same off the files, before anything is pushed.
Who translates
You do, in the files: an agent is a translator in its own right, and nothing routes it through a machine. Machine translation (DeepL) is a panel action for a person — the owner, an editor, the studio — and off on a platform without a DeepL key; no tool of yours reaches it, and the platform refuses an agent there. Words it writes are recorded by: machine, shown in the panel as unchecked until a person reads them, and reach visitors only through a version and a publish, like a person's. After a pull they are in the files like any translation: keep them, or write over them — yours are recorded as the agent's. Never call a translation service from a build, and never write a machine's words into the files as yours.
The panel writes a person's words into the same translations (by: person): pull before you edit them, as for any content.
Before the push
npx @jtakeit/astro schemajudges every translation as the import will: beside its original,ofits id, in a language the schema names, holding only words.validate_schemawith the schema, thejtk/files — every translation among them — andsite_id: the platform's own judge, the same as the import's.- After the build,
get_built_pageon/en/…reads a language as a visitor does;jtkit linton your own build checks every language's pages.
An older site, on contract 2
A contract-2 site keeps a full copy of every document per language, under jtk/content/<locale>/…, and a photograph changed in one language stays old in the others. jtk upgrade contract-3 moves it: each copy becomes a translation beside its original, and a value that differs between languages where it should be one — two photographs, two prices — stops the move and is listed for an answer. The platform's team moves every live site itself; a new site is on contract 3 from jtk create.