i18n.md

Internationalization (i18n)

Head Start supports multi-language websites with localised routing, localised content and translations.

Configuration

Supported locales and the default locale are defined in src/lib/i18n.ts. You can access these anywhere using:

import { defaultLocale, locales } from '@lib/i18n';

Middleware is used to automatically set the current locale based on the current route (see routing below). You can also manually change the current locale using:

import { setLocale } from '@lib/i18n';
const currentLocale = setLocale('fr');
// note: locale is only changed if in list of configured locales.

You can get the current locale in any page and component template using:

import { getLocale } from '@lib/i18n';
const currentLocale = getLocale();

Routing

All page routes are localised using a dynamic route parameter: src/pages/[locale]/. This means the current locale is always available via Astro.params.locale in Astro page templates.

A website visitor is automatically redirected to the right locale when visiting the root url /, using an API route as the page root: src/pages/index.ts.

A website visitor can switch between the available locales using the LocaleSelector component. To make alternate page-specific URLs available, you must pass them to the default Layout component from your page template:

---
import Layout from '@layouts/Default.astro';

---
<Layout 
  pageUrls={[
    { locale: 'en', pathname: '/en/some/path/' },
    { locale: '..', pathname: '...' },
  ]}
  { ...otherProps }
>

Translations

Head Start uses Rosetta for translations. Rosetta is an internationalization (i18n) library, selected for its small footprint (<300 bytes) and for being framework agnostic. It can used in Astro templates, client-side scripts and in UI frameworks like React, Svelte and Vue.

Translations can be managed in the CMS and are automatically loaded pre build and pre dev. You can use them anywhere using their key value with Rosetta's t() function, made available from src/lib/i18n.ts:

import { setLocale, t } from '@lib/i18n';

setLocale('nl');

t('play_video'); 
// returns 'video afspelen' (translation from CMS)

Rosetta also supports params. For instance a translation in the CMS with key watch_video_on_provider can have a parameter in it's value like "bekijk op {{provider}}":

t('watch_video_on_provider', { provider: 'YouTube' });
// return 'bekijk op YouTube' (translation with param from CMS)