Content & media
Languages & translation
One site in several languages: adding a language, translating on the page and in the Translate view, AI and agents, content per language, addresses, domains and what search engines get.
A page has one layout and words per language. The layout belongs to the site’s own language; a translation holds only what differs: the text, the attributes that are words (alt text, titles, labels, placeholders), a link typed by hand, a different picture. Fix the layout once and every language has the fix.
Each language is still written as plain files. The German about page is src/pages/de/ueber-uns.astro with the German words in it, and a template or component with words of its own gets one file per language. Delete sitereal and every page is a readable page in its own language.
Adding a language
Settings → Languages holds the site’s own language at the top and every other one below it. Add a language offers a list, or takes any language code (pt-BR, de-CH). Per language you set:
- Live or In progress. A language in progress can be translated and previewed on the canvas, and nothing of it is written into the site or published. Switch it to Live when it is ready.
- The prefix, its folder in the address. It is the code unless you set one (
/de/). - An own domain, for a language that should be a site of its own (see below).
- Its flag, for a switcher that shows flags. A flag is a country, not a language, so none shows unless you pick a look with flags.
The row says how far the language is, in percent. Removing a language asks first: its pages go, and its words stay in the project in case it comes back.
Addresses
Adding a language moves no address. The site’s own language stays at /, and the others go under their prefix. The language in the address puts it before the path (/de/services, what most sites do) or after it (/services/de). A page can have its own address in a language, like /de/ueber-uns, set in its page settings in that language.
Every language has a prefix puts the site’s own language under its folder too, as on a site launched in several languages at once: /about becomes /en/about. At / is then a page of yours that offers the languages, or a step on to /en/. On a live site this moves every address, so the switch says so before it does.
Visitors are never redirected by their browser’s language, which Google advises against. The suggestion offers it instead.
The Translate view
Once a site has another language, Translate appears in the sidebar beside Content. Its rail lists the languages with how far each is, then Everything, Pages, Collections and More (templates, components, popups, forms, terms and the site’s own words). The table puts the source, the translation and its status side by side.
| Status | Means |
|---|---|
| Missing | Nothing written in this language yet. The page shows the source’s words. |
| Outdated | The source changed after it was translated. |
| Machine | Written by an AI or an agent, and not looked at by a person yet. |
| Done | Written or reviewed by a person, for the source as it is now. |
The status is worked out, never ticked by hand: each translated string remembers a short fingerprint of the words it was translated from. When you change the source and the translation still fits, the toast that appears offers Still fits, so a typo fix does not mark every language outdated.
- Enter saves and moves down, ⌘↵ marks a row reviewed, Esc puts the box back, and ⌥↑ ⌥↓ move between rows.
- Same words once, on by default, shows words that appear in several places as one row (Read more on thirty cards). Saving it writes every place.
- The glossary terms a string holds show under the source, and the box says when a translation leaves one out.
Translating on the page
On the page in the Translate view, or the eye on a row, opens the canvas in translate mode. The bar over the canvas says Translating into Deutsch, and the canvas shows the page in that language, with its lang and dir, so hyphenation and right-to-left are previewed as they ship.
- Type on the canvas, or click an element: the panel shows each of its words with the source above and a box for this language. Emptying a box gives the field back to the source.
- Leave out of Deutsch hides the element in that language only. With nothing selected, the panel lists what is left out, each with Bring back, and holds the page’s title, description and address in the language.
- List goes back to the row you came from, and Done ends translate mode. Opening another view ends it too.
There is no Style panel in translate mode, because the layout is the site language’s. Adding, moving or styling an element is not carried out there; a message says why. When a page really needs a different layout in one language, Own Deutsch layout gives that language its own copy. It asks first, the page stops following the source from then on, and Follow English again goes back.
Translating with AI and agents
AI in the Translate view translates the rows you pick, or every row still to do. Set it up under Settings → Languages → Translating with AI, in one of three ways:
- A command on this computer, which reads the prompt and answers on its own: Claude Code (
claude -p, with its own sign-in), Ollama orllm. - An OpenAI-compatible API: OpenAI, OpenRouter, Mistral, Groq, Gemini, or Ollama or LM Studio running on this computer, which need no key.
- The Anthropic API, for Claude directly.
A key is the name of an environment variable, never the key itself, and the choice belongs to this computer rather than the project, so a project you open cannot make sitereal start anything. What comes back is checked like any other write and marked as a machine’s, so it stays visible until someone has read it. A machine never writes over a person’s words. A run takes up to four hundred strings, and one undo takes it all back.
An agent connected over the MCP needs none of this: sitereal_translations hands it the strings with their context and glossary terms, and sitereal_save_translations takes its translations back, refusing any written for a source that has changed since. For an agent, in the Translate view’s menu, copies what to tell it.
Settings → Languages → Glossary lists terms that are never translated (your brand, product names) or always said one way in a language, and How the site speaks is a note on tone. AI runs and agents get both.
Content in several languages
A content type is translated or not, which you set on the type in the Content hub. In a translated type each field is translated or shared. Text, Long text, links and alt text are translated by default. Files, numbers, dates, switches, a select’s value, lists and groups are shared, so a German edit cannot change an English date. A select keeps one stored value and gets a label per language, so filters and conditions work the same in every language.
- Entry files: a translation is a complete file beside its original,
on-light.de.md, with the shared values copied in. Open it and you see the whole entry. - A data file: each language gets
src/data/<type>.de.json, remade from the project’s rows on every save. Edit the rows, not that file. - A database type keeps its words in a table beside its own,
<type>_translations, made by the usual migration. - A data source (REST, a feed, a sheet or a CMS) can be asked once per language, with the language in its query:
langfor WordPress with WPML or Polylang,localefor EmDash.
A translated type with entry pages gets them in each language, under that language’s archive, and site search is per language. On a site with languages, the hub’s tables get a Languages column with a flag per language: grey for not started, a colored dot for how far it is, a square for an own layout, and struck through where it is left out. Click a flag to leave a page or an entry out of that language, or bring it back. Words are translated in the Translate view, never in the hub.
Words that come with the site
- Parts (search, the carousel, popups’ close buttons and the like) bring their words in eight languages, filled in when you add a language.
- The consent banner and its preferences are filled in from the same stock text in the new language. Words you changed are left for you.
- Forms answer in the language of the page they are on, both their messages and their checks, and record the language with each submission.
- The site’s own words (its name, description, title template, the publisher’s address and the small cookie banner) are rows under More → Site words, and alt text per language lives in the Media library (Alt text · Deutsch).
The switcher and the suggestion
The language switcher is under Navigation in the insert menu, with Language codes, Language flags and Flag select as ready-made looks. It is a list of links that keeps itself in step with the live languages, each going to this page in that language. It looks like a row or a dropdown, and shows names, codes, flags or a flag with either. The name is always what a screen reader reads, and without JavaScript the dropdown is shown as a row.
Settings → Languages → Suggest the visitor’s language adds a bar that tells a German browser on an English page Diese Seite gibt es auch auf Deutsch, in German, with a link, once. It never redirects. Its words are translated like any popup’s, and it needs the site’s Production URL (Settings → General) to find the other language’s page.
What search engines get
Without any setup, every language gets <html lang> (and dir="rtl" where the language needs it), a canonical of its own, hreflang alternates in both directions with x-default, sitemap alternates, and og:locale. Alternates need absolute addresses, so they are written once the Production URL is set, and the build check says so until then.
Each language has its own 404 page where the host can serve one per folder: the export’s .htaccess does it on web hosting, and publishing to Vercel, Netlify or Cloudflare says it in each host’s own way. For a right-to-left language, Settings → Languages offers to add dir to your PlainBase.astro if it does not take one yet.
A language on its own domain
Give a language a domain, like example.de, and it becomes a site of its own made from the same build. Its pages stay in its folder in the project, and every address of it is https://example.de/… with the folder taken off: links, canonicals, alternates, the switcher, entries and search.
Publish uploads the site without that folder, then the folder as a second site on the same host account, named after the site (my-site-de), made if it is missing. Pointing the domain at it is yours to do, at the host and in DNS, and the publish says where. This needs publishing by upload to Vercel, Netlify or Cloudflare. A host that builds from GitHub, web hosting by FTP and a site with a server each publish one site, so the checks stop and say why. The static export says which folder to upload where.
A language’s files can be edited by hand. Change src/pages/de/ueber-uns.astro in your editor or let an agent do it, and the change is read back into that language. Delete an element there and it is left out of that language. Each file carries a mark that says which language and page it was written for.