Skip to content

Multi-Language Sites ​

A multi-language Kirby pairs with Nuxt i18n: the locale i18n resolves is the language you pass to a query.

Install Nuxt i18n ​

Install the official Nuxt i18n module before proceeding:

bash
npx nuxt module add i18n

Pass the Language to a Query ​

To fetch language-specific content, pass the language option with your query. You can get the current language from the useI18n composable's locale:

ts
const { locale } = useI18n()

// Get the about page in the current language
const { data } = await useKql(
  { query: 'page("about")' },
  { language: locale }
)

language takes a string, a ref or a getter and is part of the key, so each language gets an entry of its own, and a language switch sends the query again in the new language.

The language option travels as the X-Language header, which Kirby reads on every API route – a code no language matches falls back to the default language instead of erroring. useKirbyData and $kirby accept it too:

ts
const { data } = await useKirbyData('api/__sitemap__', {
  language: locale
})

Fetching Content Outside the API ​

Kirby itself reads X-Language only for requests below /api. Kirby Headless 8.1 extends it to the headless.globalRoutes catch-all, so a page fetched by its own path honors language too – as long as the path carries no language prefix of its own:

ts
const { data } = await useKirbyData('about', {
  language: locale
})

Two conditions hold there and nowhere else. The request has to arrive at the language Kirby serves from the root: a prefixed URL keeps the language it names, so on a site that prefixes every language, the header has no effect. And a code no language matches is ignored rather than falling back to the default.

Everywhere else the language belongs in the path, and language has nothing to act on:

ts
// Resolves to `/de/about` on the Kirby side
const { data } = await useKirbyData(`${locale.value}/about`)

Handling Dynamic Routes ​

For dynamic routes like pages/[...slug].vue, you will need to handle both the language code and the page slug. With prefixed routes (e.g., /en/about, /de/about), the language code is part of the URL.

To trim the leading language code from the slug, create a utility function in app/utils/locale.ts to build the non-localized slug:

ts
export function getNonLocalizedSlug(
  param: string | string[],
  locales: string[] = []
) {
  if (Array.isArray(param)) {
    param = param.filter(Boolean)

    // Remove locale prefix if present
    if (param.length > 0 && locales.includes(param[0]!)) {
      param = param.slice(1)
    }

    return param.join('/')
  }

  return param
}

Then, use this function in your page component to fetch the content based on the current route path and locale:

vue
<script setup lang="ts">
const { locale, localeCodes } = useI18n()
const route = useRoute()

// Extract the non-localized slug
const pageUri = getNonLocalizedSlug(route.params.slug ?? '', localeCodes.value)

// Fetch page data for current language
const { data: pageData, error: pageError } = await useKql(
  {
    query: `page("${pageUri || 'home'}")`,
    select: { title: true }
  },
  { language: locale }
)
</script>

Handle Missing Pages ​

When working with translated content, you may want to handle pages that do not exist in the requested language or do not exist at all. You can check if the query returned a valid result and handle it accordingly.

ts
// Handle missing content
if (!pageData.value?.result) {
  // Load error page in current language
  const { data } = await useKql(
    { query: 'page("error")' },
    { language: locale }
  )

  const event = useRequestEvent()
  if (event)
    setResponseStatus(event, 404)

  // Now, use `data` to render the error page
}

Released under the MIT License.