---
title: "Internationalization (i18n)"
description: "Base setup on top of headless services to help you get started quickly"
language: "English"
url: "https://head-start.pages.dev/en/documentation/i18n/"
---

Copy page

* [Open in Claude ](https://claude.ai/new?q=Read+from+this+URL%3A+https%3A%2F%2Fhead-start.pages.dev%2Fen%2Fdocumentation%2Fi18n%2F+and+explain+it+to+me.)
* [Open in ChatGPT ](https://chatgpt.com/?hints=search\&q=Read+from+this+URL%3A+https%3A%2F%2Fhead-start.pages.dev%2Fen%2Fdocumentation%2Fi18n%2F+and+explain+it+to+me.)

# Internationalization (i18n)

!Note: this page is auto-generated from [docs/i18n.md](https://github.com/voorhoede/head-start/tree/main/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`](https://github.com/voorhoede/head-start/tree/main/src/lib/i18n/index.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](#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](https://docs.astro.build/en/core-concepts/routing/#dynamic-routes): [`src/pages/[locale]/`](https://github.com/voorhoede/head-start/tree/main/src/pages/%5Blocale%5D/). 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](https://docs.astro.build/en/core-concepts/endpoints/#server-endpoints-api-routes) as the page root: [`src/pages/index.ts`](https://github.com/voorhoede/head-start/tree/main/src/pages/index.ts).

A website visitor can switch between the available locales using the [`LocaleSelector` component](https://github.com/voorhoede/head-start/tree/main/src/components/LocaleSelector/). 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](https://github.com/lukeed/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](https://github.com/lukeed/rosetta#rosettatkey-params-lang), made available from [`src/lib/i18n.ts`](https://github.com/voorhoede/head-start/tree/main/src/lib/i18n/index.ts):

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

setLocale('nl');

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

[Rosetta also supports params](https://github.com/lukeed/rosetta#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](https://www.datocms.com/plugins/datocms-plugin-translate-fields/). You need to enable it on fields, and configure it with a translation service like [DeepL](https://www.deepl.com/) 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.