Skip to content

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.json

It 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, its seo and 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 its fields, and blocks — an entry's body is whole per language: a translation with blocks of 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 no of: the file beside it names it. So would a module's settings, where a module says a field is localized; the bookings and the shop have nothing to translate.

Which values are words ​

The field's kind decides, unless the field says localized:

per languagethe 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 sluga 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 from is empty is no record.
  • A malformed record — from not eight hex digits, by not 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": false in 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 picks are the original's. The page sends its locale with 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-CH is 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 schema judges every translation as the import will: beside its original, of its id, in a language the schema names, holding only words.
  • validate_schema with the schema, the jtk/ files — every translation among them — and site_id: the platform's own judge, the same as the import's.
  • After the build, get_built_page on /en/… reads a language as a visitor does; jtkit lint on 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.