LanguagesLocales and routing

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.

View as Markdown

Declaring the languages

The config names the default language and the supported set. A single-language site declares one:

smoodly/config.ts
  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:

astro.config.ts
  i18n: { locales: ["en", "fi"], defaultLocale: "en" },
src/smoodly/config.ts
  locales: { default: "en", supported: ["en", "fi"] },

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:

src/layouts/Layout.astro
---
// …
  ? 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.

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.

Next, Localized fields.

Edit this page on GitHubLast updated 13 Nov 2026