Locales and routing
A site publishes in one language or several. This page covers declaring the languages, how each gets its own URLs, and what editors see when a page exists in some languages and not others.
Declaring the languages
The config names the default language and the supported set. A single-language site declares one:
locales: { default: "en", supported: ["en"] },A multilingual site, which the installer scaffolds when you answer yes to multilingual, names the set twice: in i18n in astro.config.ts, for Astro's routing, and in the config. The installer writes both, and the site refuses to start when they disagree:
i18n: { locales: ["en", "fi"], defaultLocale: "en" }, locales: { default: "en", supported: ["en", "fi"] },A multilingual site, which the installer scaffolds when you answer yes to multilingual, keeps the set in one place for next-intl and imports it into the config:
export const routing = defineRouting({
locales: ["en", "fi"],
defaultLocale: "en",
localePrefix: "as-needed",
alternateLinks: false,
localeDetection: false,
}); locales: { default: routing.defaultLocale, supported: [...routing.locales] },The config cannot go the other way round: the proxy that routes languages runs in the edge runtime and cannot load the registry.
A locale code is a plain string such as en, fi, en-US or zh-Hant. Adding a language later is a config change; every fixed page and global gets a row in it on the next admin load.
One URL per language
Every page and entry has its own slug in each language it exists in, so URLs translate whole: /company/about-us in English can be /fi/yritys/tietoa in Finnish. Fixed pages and collection paths take a per-language map in code; the starter's Articles index is posts in English and artikkelit in Finnish.
The language prefix is Astro's: the default language has none, unless routing: { prefixDefaultLocale: true } in i18n says so, and the others get theirs. Smoodly follows the same rule. href from smoodly/astro/runtime turns a language-relative path into a site URL, and everything that hands out a URL goes through it:
---
// …
? codes.map((code) => ({ code, url: href(locales[code]?.path ?? "/", code), current: code === locale }))
// …
---On a single-language site it returns the path unchanged. The admin sits outside the language prefix. A site that prefixes the default language says so in the config too, with routing: { prefixDefaultLocale: true }, so the links Smoodly builds for editors carry the prefix; the site refuses to start when the two disagree.
The language prefix is next-intl's: with as-needed, the default language has none and the others get theirs. Smoodly never adds a prefix itself. One function in smoodly/server.ts turns a language-relative path into a site URL, and everything that hands out a URL goes through it:
export const href = (path: string, locale: string) => getPathname({ locale, href: path });On a single-language site the same function returns the path unchanged. The proxy skips /admin, which sits outside the language segment and has no prefix. A site whose localePrefix is always says so in the config too, with routing: { prefixDefaultLocale: true }, so the links Smoodly builds for editors carry the prefix.
Pages that exist in some languages
A page or an entry exists in the languages it has been added to, and nothing falls back: a page that exists only in Finnish is a 404 in English. The pages list and every collection list have a language picker, and a page missing from the selected language shows dimmed, with Add en in its menu.
Adding a language copies the content on screen as the first draft in the new language, for the editor to translate. A page can be added to a language only when its parent exists there, and removed from one only while no child page has it. Fixed pages, collection mounts and globals exist in every language from the start and never lose one.
Publishing is per language. A page published in English and edited in Finnish is Published in one and Unpublished changes in the other, and each language has its own history.
One order, or one per language
Editors drag pages into an order in the page tree, and entries in a collection ordered "manual". By default that order is shared: a drag made in any language reorders every language.
Add order: "perLocale" to locales in the config, next to default and supported, and each language keeps its own. A drag then reorders only the language selected in the list, and the page tree, a page's children and a manual collection's queries return the order of the language they are read in. Until an editor drags, every language has the order it had before.
Only the order differs. A page still sits under the same parent in every language; moved under a new parent, it lands where it was dropped in the selected language and last in the others. A page added to a language starts where the language it was copied from has it.
Setting order back to "shared" (or removing it) keeps each language's order as it is until the next drag among the same siblings, which every language then takes.
The site's own words
Labels that are not content, such as All articles or min read, are yours to translate.
The starter keeps them in src/messages/<locale>.json and reads them through src/strings.ts, with no library behind it. A language without its own file shows the English words.
The multilingual starter keeps them in messages/<locale>.json and reads them through next-intl; the single-language starter ships the English map with no library behind it.
Next, Localized fields.