Brease Docs

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:

StrategyIn the appExample
PREFIX_EXCEPT_DEFAULT (default)Prefix all but the default locale/about, /de/about
PREFIX_ALLPrefix every locale/en/about, /de/about
CUSTOMCustom templatea 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.

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 templates
app/[[...path]]/layout.tsx
import { 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>
  )
}
app/[[...path]]/page.tsx
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}>, with aria-current on 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.

On this page