Skip to content
[Logo] [Logo]

Internationalization (i18n)

!Note: this page is auto-generated from docs/i18n.md.

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)

Translating CMS content

You can easily translate CMS content via the Translate Fields plugin. You need to enable it on fields, and configure it with a translation service like DeepL in order to use it.

Enabling the Translate Fields plugin

  • Go to the DatoCMS project settings.

  • Click on the Plugins tab.

  • Click on the Translate plugin.

  • Enable Auto-apply to fields to automatically apply the plugin to all text-based fields in all models and blocks.

  • Choose a translation service.

  • Add the API key.

Using the Translate Fields plugin

Fields that have the Translate Fields plugin enabled will show a "Translate" button in the DatoCMS editor to translate it to another locale.

Translate Fields might translate text that is not meant to be translated. Adding names of fields to Exclude keys makes it possible to exclude those fields from translation. For example, you can exclude the variant field of a model by adding variant to the Exclude keys field in the Translate Fields plugin settings.