# 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:

File: `smoodly/config.ts`

```ts
  locales: { default: "en", supported: ["en"] },
```

**Astro**

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:

File: `astro.config.ts`

```ts
  i18n: { locales: ["en", "fi"], defaultLocale: "en" },
```

File: `src/smoodly/config.ts`

```ts
  locales: { default: "en", supported: ["en", "fi"] },
```

**Next.js**

A multilingual site, which the installer scaffolds when you answer yes to *multilingual*, keeps the set in one place for [next-intl](https://next-intl.dev) and imports it into the config:

File: `i18n/routing.ts`

```ts
export const routing = defineRouting({
  locales: ["en", "fi"],
  defaultLocale: "en",
  localePrefix: "as-needed",
  alternateLinks: false,
  localeDetection: false,
});
```

File: `smoodly/config.ts`

```ts
  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.

**Astro**

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:

File: `src/layouts/Layout.astro`

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

**Next.js**

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:

File: `smoodly/server.ts`

```ts
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.

**Astro**

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.js**

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](https://smoodly.io/docs/languages/localized-fields.md).
