Locales and routing
URL strategies, and the route structure that makes adding a locale a setting instead of a code change.
URL strategies
Each site has a list of locales (the first is the default) and a URL strategy, set in Site settings › General:
| Strategy | In the app | Example |
|---|---|---|
PREFIX_EXCEPT_DEFAULT (default) | Prefix all but the default locale | /about, /de/about |
PREFIX_ALL | Prefix every locale | /en/about, /de/about |
CUSTOM | Custom template | a urlTemplate with {locale} and {slug} |
Locale codes are BCP 47: a language, an optional script and an optional region (en, de-AT, pt-BR). Switching to Prefix every locale changes every URL of the default locale, so add redirects from the old URLs.
brease.resolve(pathname) and brease.route(segments) turn a URL into { slug, locale } for any strategy; buildPath and localeHref go the other way.
Recommended structure
brease-client works with any routing. This structure is what Brease recommends, and what the AI moves a site towards when asked to serve a new locale: locales become a setting, so adding one or changing the URL strategy needs no code change.
app/
[[...path]]/
layout.tsx root layout: <html lang>, the locale context for the page
page.tsx every page in every locale; the page's content picks its template
not-found.tsx
og/[[...path]]/route.tsx share images (image files can't sit inside an optional catch-all)
api/…, sitemap.ts, robots.ts unchanged: static routes win over the catch-all
brease/templates.tsx { home: …, article: … }, the site's own page templatesimport { brease } from '@/lib/brease'
import { LocaleProvider } from '@/components/locale' // the site's own React context
type Props = { children: React.ReactNode; params: Promise<{ path?: string[] }> }
export default async function RootLayout({ children, params }: Props) {
const site = await brease.getSite()
const context = (await brease.localeContext((await params).path)) ?? {
locale: site.defaultLocale,
settings: site,
alternates: {},
homes: {}
}
return (
<html lang={context.locale}>
<body>
<LocaleProvider value={context}>{children}</LocaleProvider>
</body>
</html>
)
}import { notFound } from 'next/navigation'
import { toMetadata } from 'brease-client/next'
import { templates } from '@/brease/templates'
import { brease } from '@/lib/brease'
export const revalidate = 60
type Props = { params: Promise<{ path?: string[] }> }
async function load(params: Props['params']) {
const route = await brease.route((await params).path)
const page = route && (await brease.getPage<Content>(route.slug, { locale: route.locale }))
const Template = page && templates[page.content.template]
return page && route && Template ? { page, locale: route.locale, Template } : null
}
export async function generateStaticParams() {
try {
return await brease.routes()
} catch (err) {
console.warn(`Brease pages unavailable at build time: ${(err as Error).message}`)
return []
}
}
export async function generateMetadata({ params }: Props) {
const loaded = await load(params)
return loaded ? toMetadata(loaded.page.resolvedSeo) : {}
}
export default async function Page({ params }: Props) {
const loaded = await load(params)
if (!loaded) notFound()
// Pass the locale to everything else that reads Brease: navigations, "_" pages, site SEO.
return <loaded.Template page={loaded.page} locale={loaded.locale} />
}Heads up
Don't keep app/[slug] or app/[locale] folders next to the catch-all, and don't add middleware for locales: two dynamic folders side by side break routing at runtime, and type checks don't catch it. brease.route() handles every strategy.
Locale switcher
import { localeHref, localeLinks } from 'brease-client'
const context = await brease.localeContext(path) // { locale, settings, alternates, homes }
localeLinks(context) // [{ locale: 'hu', label: 'Magyar', href: '/rolunk', current: true }, …]
localeHref(context.settings, 'about', 'de') // '/de/about'localeLinks()links each locale's version of the current page, or that locale's home page. Locales without content yet are left out.- Render it as a list of
<a href={l.href} hreflang={l.locale}>, witharia-currenton the current one, and hide it while there are fewer than two links. - Everything that read a fixed locale (
getPage,getNavigation,site.seo.hu) takes the locale from the route instead. - Links inside content are already locale URLs. Build other internal links with
localeHref(settings, slug, locale). - Text written into components (button labels, captions) stays as it is. Moving it into content is a separate change.