astro-i18next

An astro integration of i18next + some utility components to help you trans...

Internationalization i18n Astro

yassinedoghri/astro-i18next astro-i18next.yassinedoghri.com astro-i18next

README

🧪 astro-i18next

An astro integration of

i18next + some utility components to help you

translate your astro websites!

[![npm-badge]][npm] [![build-badge]][build] [![codecov-badge]][codecov] [![license-badge]][license] [![contributions-badge]][contributions] [![semantic-release-badge]][semantic-release] [![stars-badge]][stars]

Note

Status - 🚧 Beta

[👉 Road to v1.0.0](https://github.com/yassinedoghri/astro-i18next/issues/19)

You can use it, and feedback is more than welcome! Note that some breaking

changes may still be introduced during this phase as the goal for v1 is to get

the best possible DX for translating your Astro pages.

Examples

Example	Status
-------------------------------------	----------------------------------------------------------------------------------------------------
[SSG	[![example-up-badge]](examples/basics)
[SSR	[![example-up-badge]](examples/node)
[React](examples/react)	[![example-up-badge]](examples/react)
[SSR	[![example-down-badge]](examples/netlify)
SSR	[![example-down-badge]](examples/basics)

- Examples

- 🚀 Getting started

- 1. Install

- 2. Configure

- 3. Start translating

- 💻 CLI commands

- generate

- 🔄 Translate Routes

- 📦 Utility components

- Trans component

- LanguageSelector component

- HeadHrefLangs component

- 📦 Utility functions

- interpolate function

- localizePath function

- localizeUrl function

- 👀 Going further

- Namespaces

- AstroI18nextConfig Props

- ✨ Contributors

- ❤️ Acknowledgments

- 📜 License

🚀 Getting started

1. Install

``` sh
npm install astro-i18next
```

2. Configure

1. Add astro-i18next to your astro.config.mjs:

``` js
import { defineConfig } from "astro/config";
import astroI18next from "astro-i18next";
export default defineConfig({
integrations: [astroI18next()],
});
```

2. Configure astro-i18next in your astro-i18next.config.mjs file:

``` js
/** @type {import('astro-i18next').AstroI18nextConfig} */
export default {
defaultLocale: "en",
locales: ["en", "fr"],
};
```

ℹ️ Your astro-i18next config file can be a javascript (.js | .mjs |

.cjs) or typescript (.ts | .mts | .cts) file.

ℹ️ For a more advanced configuration, see the

AstroI18nextConfig props.

3. By default, astro-i18next expects your translations to be organized inside

your

[astro's publicDir](https://docs.astro.build/en/reference/configuration-reference/#publicdir),

in a locales folder:

``` sh
public
└── locales # create this folder to store your translation strings
├── en
| └── translation.json
└── fr
└── translation.json
```

ℹ️ astro-i18next loads your translation files both server-side and

client-side using

i18next-fs-backend and

i18next-http-backend

plugins.

ℹ️ You may choose to organize your translations into multiple files instead

of a single file per locale using namespaces.

3. Start translating

You may now start translating your pages by using

[i18next's t function](https://www.i18next.com/overview/api#t) or the

Trans component depending on your needs.

Here's a quick tutorial to get you going:

1. Use translation keys in your Astro pages

```astro
---
// src/pages/index.astro
import i18next, { t } from "i18next";
import { Trans, HeadHrefLangs } from "astro-i18next/components";
---
<html lang={i18next.language}>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width" />
<title>{t("site.title")}</title>
<meta name="description" content={t("site.description")} />
<HeadHrefLangs />
</head>
<body>
<h1>{t("home.title")}</h1>
<p>
<Trans i18nKey="home.subtitle">
This is a <em>more complex</em> string to translate, mixed with <strong
>html elements
</strong> such as /example.com/">a cool link</a>!
</Trans>
</p>
</body>
</html>
```

``` json
// public/locales/en/translation.json
{
"site": {
"title": "My awesome website!",
"description": "Here is the description of my awesome website!"
},
"home": {
"title": "Welcome to my awesome website!",
"subtitle": "This is a <0>more complex</0> string to translate, mixed with <1>html elements</1>, such as a <2>a cool link</2>!"
}
}
```

``` json
// public/locales/fr/translation.json
{
"site": {
"title": "Mon super site web !",
"description": "Voici la description de mon super site web !"
},
"home": {
"title": "Bienvenue sur mon super site web !",
"subtitle": "Ceci est une chaine de charactères <0>plus compliquée</0> à traduire, il y a des <1>éléments html</1>, comme <2>un super lien</2> par exemple !"
}
}
```

2. Create localized pages using the generate command

``` sh
npx astro-i18next generate
```

3. You're all set! Have fun translating and generate localized pages as you go

🚀

Note

For a real world example, see the demo project or try the _Astro

i18n basics example_ on StackBlitz:\

💻 CLI commands

generate

``` sh
npx astro-i18next generate
```

This command will generate localized pages depending on your config and set

i18next's language change on each page.

For instance, with locales = ["en", "fr", "es"], and "en" being the default

locale and having:

``` sh
src
└── pages
├── about.astro
└── index.astro
```

👇 Running npx astro-i18next generate will create the following pages

``` sh
src
└── pages
├── es
| ├── about.astro
| └── index.astro
├── fr
| ├── about.astro
| └── index.astro
├── about.astro
└── index.astro
```

🔄 Translate Routes

astro-i18next let's you translate your pages routes for each locale!

For instance, with support for 3 locales (en, fr, es), en being the

default and the following pages:

``` sh
src
└── pages
├── about.astro
├── contact-us.astro
└── index.astro
```

1. Set route mappings in your astro-i18next config:

``` js
/** @type {import('astro-i18next').AstroI18nextConfig} */
export default {
defaultLocale: "en",
locales: ["en", "fr", "es"],
routes: {
fr: {
"about": "a-propos",
"contact-us": "contactez-nous",
"products": {
"index": "produits",
"categories": "categories",
}
}
es: {
"about": "a-proposito",
"contact-us": "contactenos",
"products": {
"index": "productos",
"categories": "categorias",
}
}
},
};
```

2. Generate your localized pages using the generate CLI command,

they will be translated for you!

``` sh
src
└── pages
├── es
| ├── productos
| | ├── categorias.astro
| | └── index.astro
| ├── a-proposito.astro
| ├── contactenos.astro
| └── index.astro
├── fr
| ├── produits
| | ├── categories.astro
| | └── index.astro
| ├── a-propos.astro
| ├── contactez-nous.astro
| └── index.astro
├── products
| ├── categories.astro
| └── index.astro
├── about.astro
├── contact-us.astro
└── index.astro
```

Note

The localizedPath and

localizeUrl utility functions will retrieve the

correct route based on your mappings.

📦 Utility components

Trans component

A component that takes care of interpolating its children with the translation

strings. Inspired by

react-i18next's Trans component.

```astro
---
import { Trans } from "astro-i18next/components";
---
<Trans i18nKey="superCoolKey">
An <a href="https://astro.build" title="Astro website">astro</a> integration of
<a href="https://www.i18next.com/" title="i18next website">i18next</a> and utility
components to help you translate your astro websites!
</Trans>
```

``` json
// fr.json
{
"superCoolKey": "Une intégration <0>astro</0> d'<1>i18next</1> + quelques composants utilitaires pour vous aider à traduire vos sites astro !"
}
```

Trans Props

Prop	Type	Description
---------	-------------------	--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
i18nKey	?string	Internationalization
ns	?string	Namespace

LanguageSelector component

Unstyled custom select component to choose amongst supported locales.

```astro
---
import { LanguageSelector } from "astro-i18next/components";
---
<LanguageSelector showFlag={true} class="my-select-class" />
```

LanguageSelector Props

Prop	Type	Description
---------	------------------	---------------------------------------------------------
showFlag	?boolean	Choose

HeadHrefLangs component

HTML tags to include in your page's `` section to let search engines know

about its language and region variants. To know more, see

Google's advanced localized versions.

```astro
---
import i18next from "i18next";
import { HeadHrefLangs } from "astro-i18next/components";
---
<html lang={i18next.language}>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width" />
<title>...</title>
<meta name="description" content="..." />
<HeadHrefLangs />
</head>
<body>...</body>
</html>
```

The HeadHrefLangs component will generate all of the alternate links depending

on the current url and supported locales.

For example, if you are on the /about page and support 3 locales (en, fr,

es) with en being the default locale, this will render:

``` html
<link rel="alternate" hreflang="en" href="https://www.example.com/about/" />
<link rel="alternate" hreflang="fr" href="https://www.example.com/fr/about/" />
<link rel="alternate" hreflang="es" href="https://www.example.com/es/about/" />
```

📦 Utility functions

interpolate function

interpolate(i18nKey: string, reference: string, namespace: string | null): string

astro-i18next exposes the logic behind the Trans component, you may want to

use it directly.

```ts
import { interpolate } from "astro-i18next";
const interpolated = interpolate(
"superCoolKey",
'An astro integration of i18next and utility components to help you translate your astro websites!'
);
```

localizePath function

localizePath(path: string, locale: string | null = null, base: string = import.meta.env.BASE_URL): string

Sets a path within a given locale. If the locale param is not specified, the

current locale will be used.

Note

This should be used instead of hard coding paths to other pages. It will take

care of setting the right path depending on the locale you set.

```astro
---
import { localizePath } from "astro-i18next";
import i18next from "i18next";
i18next.changeLanguage("fr");
---
<a href={localizePath("/about")}>...</a>
```

localizeUrl function

localizeUrl(url: string, locale: string | null = null, base: string = import.meta.env.BASE_URL): string

Sets a url within a given locale. If the locale param is not specified, the

current locale will be used.

Note

This should be used instead of hard coding urls for internal links. It will

take care of setting the right url depending on the locale you set.

```astro
---
import { localizeUrl } from "astro-i18next";
import i18next from "i18next";
i18next.changeLanguage("fr");
---
<a href={localizeUrl("https://www.example.com/about")}>...</a>
```

👀 Going further

Namespaces

i18next allows you to organize your translation keys into

namespaces.

You can have as many namespaces as you wish, have one per page and one for

common translation strings for example:

``` sh
public
├-- locales
| |-- en
| | |-- about.json # "about" namespace
| | |-- common.json # "common" namespace
| | └-- home.json # "home" namespace
| └-- fr # same files in other locale folders
src
└-- pages
|-- about.astro
└-- index.astro
```

1. It can easily be setup using the namespaces and defaultNamespace keys,

like so:

```ts
/** @type {import('astro-i18next').AstroI18nextConfig} */
export default {
defaultLocale: "en",
locales: ["en", "fr"],
namespaces: ["about", "common", "home"],
defaultNamespace: "common",
};
```

2. Load the namespace globally using i18next.setDefaultNamespace(ns: string)

or specify it in the t function or the Trans component:

```astro
---
import { t, setDefaultNamespace } from "i18next";
import { Trans } from "astro-i18next/components";
setDefaultNamespace("home");
---
<h1>{t("myHomeTitle")}</h1>
<p>
<Trans i18nKey="myHomeDescription">
This translation is loaded from the default <strong>home</strong> namespace!
</Trans>
</p>
<p>
<Trans i18nKey="myCommonCTA" ns="common">
This translation is loaded from the <strong>common</strong> namespace!
</Trans>
</p>
<button>{t("common:buttonCTA")}</button>
```

AstroI18nextConfig Props

astro-i18next's goal is to abstract most of the configuration for you so that

you don't have to think about it. Just focus on translating!

Though if you'd like to go further in customizing i18next, feel free to tweak

your config!

Prop	Type	Description
--------------------	--------------------------------------------	------------------------------------------------------------------------------------------------------------------------------
defaultLocale	`string`	The
locales	`string[]`	Your
namespaces	`string`	String
defaultNamespace	`string`	Default
load	`Array<"server"	Load
i18nextServer	`?InitOptions`	The
i18nextServerPlugins	`?{[key:	Set
i18nextClient	`?InitOptions`	The
i18nextClientPlugins	`?{[key:	Set
routes	`[segment:	The
showDefaultLocale	`boolean`(`false`)	Whether

✨ Contributors

Thanks goes to these wonderful people

(emoji key):

_{Yassine Doghri} 💻 📖 🤔 🎨 💡 🚧	_{Davide Ceschia} 💻 🐛	_preetamslot 🐛	_Dmytro 🐛	_{Campbell He} 🐛	_MelKam 💻	_L1lith 🐛 🤔
_Anomander43 📖	_{Dominik Schöni} 💻	_{Dalibor Hon} 💻 🐛	_{Oleksii Lozoviahin} 💻	_{Alessandro Talamona} 🐛	_{Josh Kramer} 💻 🐛	_{Alexandre Fernandez} 💻 🐛