Add languages to a site, translate pages and site chrome with AI or manual drafts, track progress, and publish per locale.
Updated 28 days ago
In short
Open the Translations tab in the editor to add target languages, run AI translation jobs or create manual draft variants, edit site text per locale, and publish each language when it is ready. Choose Lite or Max translation quality, review character-based credit estimates before jobs start, and manage locale variants here. They do not appear in the Pages file tree or internal link picker. In the main publish menu, **Page content** lists every target language with an opt-in switch. Languages with pending changes show a change count and can be enabled; languages that are **Up to date** stay disabled so a site-wide publish never silently pushes draft translations live.
Enable localization
Translations require the localization feature on your organization (Organization → Features). When enabled, the editor left rail shows a Translations tab with a language icon.Your site has one source language (the default locale) and optional target languages. Visitors switch languages on the published site when more than one locale is live.
Translations tab layout
The tab uses a list-and-detail pattern:
View
What you do
Languages list
See the source language, each target language with a status word, Add language, and Glossary
Language detail
Translate or re-translate pages (grouped by collection), edit site text, unpublish or remove the language — locale publish lives in the header publish menu
Glossary
Define terms the AI translator must keep verbatim or translate consistently
Adding a language
Choose Add language and pick a locale from the curated list. Aveiro creates the locale folder structure for translated page variants.Each plan caps how many target languages a single site may have. Your source language always counts toward the total. The button and the show your allowance; when you hit the cap, Aveiro shows an upgrade prompt.
Open a target language to see its action zone and page list.
Mode
Behavior
AI translation (opt-in)
Enqueue a background job that translates pages and site chrome. Billed by source character count with a model multiplier (see below).
Manual drafts
Create empty draft variants per page when AI translation is off — fill them in from the Translations tab.
Bulk actions include Translate all, Update translations (stale pages only), and Re-translate everything (full overwrite — confirmed before running). Inside each language, pages are grouped by collection (accordion per top-level folder, with a per-collection page count). Row actions are icon-only: open in editor, update layout, and re-translate.
When you edit the source page's layout, translated variants can fall behind. Aveiro now tracks two kinds of staleness instead of one blanket Needs update flag:
Layout out of date — the source page's block structure changed. Fix it with Update layout (free, no AI credits). Matched text blocks keep their translated wording; new source blocks arrive untranslated and are counted.
Text changed — the source wording changed and needs a translator. Use Update translations or re-translate the affected pages.
Text metadata — page title, summary, tag, and description — is translated in a separate batch when AI translation is enabled. If that batch fails, the page body stays translated but the title may still show the source language. The language detail panel surfaces Translate the titles so you can retry metadata only — it never re-translates page bodies or spends credits on MDX you already have. If a flagged page has no translatable text in the source (for example an empty title), the retry clears the stale warning instead of looping with "0 titles translated".
Translation quality
When AI translation is enabled, choose Translation quality in the Translations tab:
Tier
Behavior
Lite (default)
Faster translations, fewer credits — about 1 credit per 100 source characters (minimum 5 credits per page)
Max
Stronger model for higher-quality output — 3× Lite credits for the same content
Progress and background jobs
Translation jobs run in the background. While a job is active:
A progress bar and page count update in the language detail panel after each page completes — you see progress even while a large page is still being translated
The language list row shows a live percentage that refreshes during the job and once more when all jobs finish so readiness numbers settle at their final values
Progress keeps updating even when you switch to another editor tab (Pages, Layout, AI, and so on)
Retranslate jobs (Update translations, Re-translate everything, or per-page re-translate) advance the same progress counter — each page counts once toward the total, and Re-translate everything completes when every translated page has been processed (it does not loop on the same batch). For Update translations (stale pages only), the job total reflects how many pages are stale — not every source page on the site — so progress shows meaningful movement (for example 2/2 instead of 2/21 when only two pages need refreshing)
If a job truly stalls — no page-count advance for about three minutes before the first page completes, then 90 seconds between subsequent pages — the UI warns you and offers Retry or Cancel. The first page can take longer while the AI receives, translates, and persists it; large pages and cold starts are normal. The warning is a safety net, not a sign that translation stopped.
The done page count is capped at the job total during processing, so progress never exceeds 100% (for example 55/55 instead of a runaway 4681/55) if a job retries or recounts pages.
Validation and broken blocks
Each AI-translated page is validated for MDX syntax and block-structure parity with the source. When validation fails, Aveiro runs an automatic repair pass that fixes syntax without changing translated text. Only valid output is cached in translation memory.
If blocks remain broken after repair, the language detail panel shows a Broken blocks warning that names each affected page:
Clickable paths — tap a path to open that variant in the editor
Block count per page — see how many blocks failed validation
Open first broken page — jump straight to the first affected variant
The warning explains that these are MDX syntax errors — the locale won't publish until the syntax is valid. Re-translating retries the AI repair pass. If the same block keeps failing, open the page and fix it by hand — translation variants are editable in Pages (text and component settings, not structure).
Publish {language} validates variants in that locale before going live. The main Page content publish menu validates source-language pages by default. Locale variants publish only when you opt in per language, so broken German MDX does not block publishing English.
Cost before you start
Before enqueueing AI translation, Aveiro shows a pre-flight cost estimate: how many pages the action touches, the estimated credits (based on each page's source character count and your selected translation quality), and how that compares to your remaining monthly AI budget. Translation memory hits cost nothing because no AI call is made.
Credits scale with content length: max(5, ceil(characters ÷ 100)) × tier multiplier per page. Lite uses a 1× multiplier; Max uses 3×.
Viewing translation variants in Pages
The Pages toolbar language switcher lets you preview or edit a locale's draft. Translation variants allow text and component settings edits, but not add, remove, or reorder blocks — structure follows the source page. A banner explains the constraint. Saving a hand-corrected variant marks it Reviewed; a re-translate confirm names how many reviewed pages would be overwritten. Switch back to the default language to change page structure.
While previewing a translation variant, version history and the toolbar Publish page / Unpublish actions are hidden. Publish each locale from the header Publish menu (per-language switches under Page content). Unpublish a live locale with the eye-off control in the language detail header.
Locale-aware navigation on the live site
When a visitor browses a non-default locale (for example /de/about), Aveiro prefixes internal navigation links with that locale so they stay in the same language:
Header, footer, and sidebar links
MDX links in page body copy
Collection and book block links
The default locale keeps unprefixed URLs (for example /about). External links and anchors are unchanged.
Localized nav labels — Header and sidebar navigation show each page and collection's translated title and description from the locale variant (matched via translation groups). Collection folder labels are synced from the source folder and translated with the locale — a translated sidebar no longer keeps English collection names because the locale folder metadata was empty. The site homepage title also uses the locale root variant when one exists. This runs server-side on the live site so nav chrome and SEO metadata stay in the visitor's language.
Site text (chrome strings)
Collection card content — On translated pages, Collection blocks load cards from the locale-equivalent folder (matched via translation groups), so titles, summaries, and cover images reflect the visitor's language. Folders created before translation groups may have no group id — Collection blocks then fall back to path-based locale matching (for example /getting-started/ → /de/getting-started/). Site-wide Collection scopes (all pages, root pages) filter to pages in the active locale. Page ranges authored against default-locale paths (for example a singlePageHref of /guide/intro) also match on translated visitor pages — Aveiro resolves the source slug via translation groups so localized URLs do not show an empty range.
Beyond page MDX, each locale has site text — your site name, SEO defaults, and layout chrome strings (header, footer, sidebar labels, link titles, button labels, copyright, and similar visitor-facing copy).
Open Edit site text inside a language detail panel to review and publish chrome translations separately from page content. Strings are grouped by area — metadata, header, sidebar, footer — so you can work through each section in order.
Default layout strings are included
Aveiro merges each layout slot with its variant defaults before building the catalog. Preset strings — footer link labels, header navigation items, copyright text, and other variant defaults — appear in Edit site text even if you have not customized that slot in Layout. AI translation jobs include these defaults along with any chrome you have edited.
When you change layout variants or slot props after translating, affected strings may show as stale until you re-translate or update them manually.
What visitors see on the live site
When someone browses a non-default locale (for example /de/about), Aveiro overlays the published site text for that locale onto your site name, header, footer, sidebar labels, and SEO defaults — the same strings you edit in Edit site text and publish per locale.
Some template UI labels are built into the theme rather than your site settings. Aveiro translates these automatically for the visitor's content locale:
Supported locales include English, German, Spanish, French, Hungarian, Polish, Italian, Dutch, Portuguese, Chinese, Japanese, and Korean. Unsupported locales fall back to English.
Shop product-detail accordion titles and body copy translate through Edit site text (under settings.shop.detailAccordion) and publish with the locale — same catalog as header and footer chrome.
Glossary
The Glossary entry on the translations list opens term management:
Keep verbatim — brand names, product codes, and phrases that must not change
Preferred translation — how the AI should translate a term in each target language
Glossary terms apply to AI translation only.
Publishing a language
Locale publish lives in the header Publish menu — not a separate button inside the language detail panel. Page content lists every configured target language: locales with unpublished changes show a change count and an enabled switch; locales that are Up to date appear with a disabled switch so you can see which languages exist without accidentally publishing them. Enable one or more locale switches, then click Publish. Each selected locale runs in its own pass: page variants (with broken-block validation) and site text for that locale ship together. Monolingual sites see no extra switches.
The main menu publishes only the default locale unless you opt in. After bulk re-translate or hand edits, flip the locale switch so visitors see updated MDX and site text. When you publish default-language Page content with localization enabled, Aveiro still warns if target languages have stale or missing translations — with separate dialogs for outdated pages, untranslated pages, or both. You can cancel and fix issues in the Translations tab, or choose Publish anyway. See Publishing pages.
Where locale variants do not appear
Translated pages live under locale folders (for example /de/...). To avoid confusion, Aveiro hides locale variant pages from:
The Pages file tree (the toolbar language switcher opens translations read-only for preview)
The internal link picker when editing block links
The Page content page checklist (individual variant rows) — use per-language switches under Page content in the header publish menu instead
Unpublishing a language
Use the eye-off control in a language detail panel header to take a locale off the live site without deleting anything. The control appears only when at least one page in that locale is live on the visitor site. Aveiro clears the published snapshot on every page variant in that locale and demotes published site text (header, footer, and layout chrome) back to reviewed — visitors stop seeing translated pages and chrome, but drafts stay editable in the dashboard. The language remains in your config and the visitor switcher; re-serving is one flip of that locale's switch in the header publish menu.
This is distinct from Remove language:
Action
Effect
Unpublish language
Hide live pages and visitor chrome for the locale; keep drafts and config
Remove — Keep content
Remove the locale from the site but preserve translated files
Remove — Delete content
Remove the locale and purge its pages and site text
Removing a language
Inside a language detail panel, Remove language (trash icon) offers two choices:
Keep content — remove the locale from the site but preserve translated files
Delete content — remove the locale and purge its pages and site text
API and MCP automation
Cloud agents and CI jobs can manage translations without opening the dashboard:
Task
API / MCP
Create a locale variant
`POST …/pages` with `translation_of` + `locale`, or `aveiro_create_page`
