astro-i18n

A TypeScript-first internationalization library for Astro.

Features

🪶 Lightweight.
🌏 Internationalized routing.
🔒 Type-safety and autocompletion.
🔧 Support for plurals, context, interpolations and formatters.
🚀 Built for Astro and nothing else.
💻 Astro island compatible.

Introduction

Most internationalization libraries rely on raw untyped strings to access their translations. This is equally possible with astro-i18n however it can generate project specific types to get type-safety and autocompletion for your translations.

Installation

# npm
npm install astro-i18n
# yarn
yarn add astro-i18n
# pnpm
pnpm add astro-i18n

Get started

Run the quick install command :

./node_modules/.bin/astro-i18n install
# serverless (no filesystem/node.js setup)
./node_modules/.bin/astro-i18n install --serverless

Verify that your middleware file at src/middleware.ts or src/middleware/index.ts uses the astro-i18n middleware. If the file was generated by the quick install command it should be fine.

// src/middleware.ts
import { sequence } from "astro/middleware"
import { useAstroI18n } from "astro-i18n"

const astroI18n = useAstroI18n(/* astro-i18n config, custom formatters */)

export const onRequest = sequence(astroI18n)

If you are using serverless all your initial data needs to be passed to the middleware, you should import your root astro-i18n config and pass it to the middleware.

When using node (SSR or SSG) you can either go for the same workflow as serverless or use the filesystem to store your config and translations.

If you used the quick install (with node) a config file for astro-i18n should have been generated, you will find it in your root directory (astro-i18n.config.(ts|js|cjs|mjs|json)). This is the same as passing it in the middleware parameters. Configure it as needed, you can set your primaryLocale and secondaryLocales there.

You can put your translations in four locations :

Inside the middleware config.
Inside the config file at the root.
In your src/pages folder (local page translations), see below.
In the src/i18n directory, see below.

astro-i18n works on the server-side and on the client-side so that it can work with client-side frameworks. Because of this translations are aggregated into groups:

The "common" group which is accesible on every page.
The current page group named after its route, such as "/about" or "/posts/[id]", as its name implies it's only accessible on the current page.
Any other custom group named by yourself, for example "admin". It's up to you to decide on which pages your custom group is accessible.

By default any translation accessible on the current page is visible on the client-side (you may change that in the config).

As shown in the screenshot above, local page translations can be either in src/pages or src/i18n/pages, nest them just like you do with astro file-based routing. All the following translation file formats are valid :

const regular = `${locale}.json` // fr.json
const private = `_${locale}.json` // _fr.json
const regularWithTranslation = `${locale}.${segmentTranslation}.json` // fr.translated-page-name.json
const privateWithTranslation = `_${locale}.${segmentTranslation}.json` // _fr.translated-page-name.json

These files can either be directly in the page directory or grouped in a special directory called i18n by default. Concerning custom groups, create a directory containing the translation files named after your group in src/i18n. To make them accessible in a page check the loadingRules.

To get type-safety and generate your translated routes run the following command npm run i18n:sync.

Once you have some translations you can use the main translation function t :

// src/pages/about/_i18n/en.json
{
	"my_nested": {
		"translation_key": "hello"
	}
}
// src/pages/about/_i18n/fr.a-propos.json
{
	"my_nested": {
		"translation_key": "bonjour"
	}
}

// src/pages/about/index.astro
import { astroI18n, t } from "astro-i18n"

astroI18n.locale // "en"
t("my_nested.translation_key") // hello

// src/pages/fr/a-propos/index.astro
import { astroI18n, t } from "astro-i18n"

astroI18n.locale // "fr"
t("my_nested.translation_key") // bonjour

If there's duplicate keys t will return the more specific one (custom group => local page => common group).

To translate a link use the l function, by default all route segment translations are visible on the client-side :

// src/pages/fr/a-propos/index.astro
import { astroI18n, l } from "astro-i18n"

astroI18n.locale // "en"
l("/about") // "about"

// src/pages/fr/a-propos/index.astro
import { astroI18n, l } from "astro-i18n"

astroI18n.locale // "fr"
l("/about") // "a-propos"

That's it for the basics, for more keep reading !

Configuration

`primaryLocale`

The default locale for your app.

`secondaryLocales`

All the other locales supported by your app.

`fallbackLocale`

If left undefined this will be equal to your primaryLocale, to disable it set it to an empty string. The locale to search a translation in when it's missing in another one.

`showPrimaryLocale`

Boolean deciding whether to show the default locale in the url or not.

`trailingSlash`

Possible values are "always" or "never" (default). When set to "always", generated routes will have a trailing slash.

`run`

Possible values are "server" or "client+server" (default). When set to "client+server" the available translations for the current page and all route translations will be serialized and sent to the client so that astro-i18n can work with client-side frameworks. You can disable this behaviour by setting run to "server".

`translations`

Your app translations in the following format :

{
	"common": {
		"en": {
			"hello": "Hello",
			"form": {
				// accessed with the "form.first_name" key :
				"first_name": "First name"
			}
		},
		"fr": {
			"hello": "Bonjour",
			"form": {
				"first_name": "Prénom"
			}
		}
	},
	"admin": {
		"en": {
			"how_are_you": "How are you ?"
		},
		"fr": {
			"how_are_you": "Comment allez vous ?"
		}
	},
	// routes are also a valid group, they will automatically load in the corresponding page :
	"/posts/[id]": {
		"en": {
			"bye": "Bye"
		},
		"fr": {
			"bye": "Au revoir"
		}
	}
}

`translationLoadingRules`

An array of rules specifying what group to load on which page :

[
	{
		"routes": ["^/admin.*"], // regex for all routes beginning with "/admin"
		"groups": ["^admin$"] // regex to load the "admin" group
	}
]

`translationDirectory`

Which name to use for the directories in src and in src/pages, by default it's "i18n" (/src/i18n and src/pages/i18n/src/pages/about/i18n).

{
	"i18n": "i18n",
	"pages": "i18n"
}

`routes`

Your route segment translations. This is where you can translate your routes, for example "/about" to "/a-propos".

{
	// only specify secondary locales
	"fr": {
		// "primary_locale_segment": "translated_segment"
		"about": "a-propos"
	}
}

Variants

Variants are the way that plurals and context are handled. You can set multiple variables, numbers will match the closest value however other types will only match exact matches. They are set in the translation key, here's some examples :

{
	"car": "There is a car.", // default value for "car" key
	"car{{ cars: 2 }}": "There are two cars.",
	"car{{ cars: 3 }}": "There are many cars.",
	"foo{{ multiple: [true, 'bar'] }}": "baz.",
	"context{{ weather: 'rain' }}": "It's rainy.",
	"context{{ weather: 'sun' }}": "It's sunny."
}

import { astroI18n, t } from "astro-i18n"

t("car") // "There is a car."
t("car", { cars: 0 }) // "There are two cars."
t("car", { cars: 1 }) // "There are two cars."
t("car", { cars: 2 }) // "There are two cars."
t("car", { cars: 3 }) // "There are many cars."
t("car", { cars: 18 }) // "There are many cars."
t("foo", { multiple: true }) // "baz."
t("foo", { multiple: "bar" }) // "baz."
t("context", { weather: "rain" }) // "It's rainy."
t("context", { weather: "sun" }) // "It's sunny."

Interpolations

Interpolations can be used to display dynamic data in your translation values, here's some examples :

{
	"interpolation_1": "{# variable #}",
	"interpolation_2": "{# variable(alias) #}",
	"interpolation_3": "{# variable(alias)>uppercase #}",
	"interpolation_4": "{# 15>intl_format_number({ style: 'currency', currency: currency }) #}",
	"interpolation_5": "{# { foo: 'bar'}(alias)>json(false)>uppercase #}"
}

import { astroI18n, t } from "astro-i18n"

astroI18n.locale // "en"

t("interpolation_1", { variable: "foo" }) // "foo"
t("interpolation_2", { alias: "bar" }) // "bar"
t("interpolation_3", { alias: "baz" }) // "BAZ"
t("interpolation_4", { currency: "EUR" }) // "€15.00"
t("interpolation_5") // '{"FOO":"BAR"}'
t("interpolation_5", { alias: { bar: "baz" } }) // '{"BAR":"BAZ"}'

As you can see there's multiple parts to an interpolation :

The interpolation value which is what the formatters apply on.
The interpolation alias which can either change the name of the value if it's a variable or make the value a default value replaceable by the alias variable.
The interpolation formatters which can take arguments, you can chain them and create your own. When creating a formatter, if you want it to work on the client side it must not use anything outside the function scope.

You can apply this to any value, even if it's nested or inside the formatters arguments.

Interpolation formatters

An interpolation formatter is a function that takes the interpolation value and transforms it, if there's multiple of them they will be chained. These are the default interpolation formatters :

upper() : value.toUpperCase().
uppercase() : alias for upper.
lower() : value.toLowerCase().
lowercase() : alias for lower.
capitalize() : Capitalizes the first character of value and lowers the others.
json(format = true) : JSON.stringify(value), if format is true it will format the JSON.
default_falsy(defaultValue) : When !value, defaultValue will be used instead.
default(defaultValue) : alias for default_falsy.
default_nullish(defaultValue) : When value == null, defaultValue will be used instead.
default_non_string(defaultValue) : When typeof value !== "string", defaultValue will be used instead.
intl_format_number(options, locale = astroI18n.locale) : Formats value with Intl.NumberFormat.
intl_format_date(options, locale = astroI18n.locale) : Formats value with Intl.DateTimeFormat.

If the formatter has no arguments you can write it without parenthesises, for example value>upper.

You can add your own custom formatters in the second argument of the middleware. If you want them to work on the client-side they must not use anything outside the function scope. Here's an example of a custom formatter :

export function xXify(value: unknown, repeats: unknown = 1) {
	if (typeof repeats !== "number") {
		throw new Error("repeats must be a number")
	}
	if (repeats <= 0) return value
	return `${"xX".repeat(repeats)}${value}${"Xx".repeat(repeats)}`
}

// example that wouldn't work client-side :
const error = new Error("repeats must be a number")
function xXify(value: unknown, repeats: unknown = 1) {
	if (typeof repeats !== "number") throw error // cannot use anything outside of scope
	// ...
}

Reference

`defineAstroI18nConfig`

function defineAstroI18nConfig(
	config: Partial<AstroI18nConfig>,
): Partial<AstroI18nConfig>

Utility function to get type safety when defining the config.

`useAstroI18n`

function useAstroI18n(
	config?: Partial<AstroI18nConfig> | string, // string if path to config file
	formatters?: {
		[name: string]: (value: unknown, ...args: unknown[]) => unknown
	},
): AstroMiddleware

The astro-i18n middleware, mandatory to make the library work.

`createGetStaticPaths`

function createGetStaticPaths(
	callback: (
		props: GetStaticPathsProps,
	) => GetStaticPathsItem[] | Promise<GetStaticPathsItem[]>,
): GetStaticPathsItem[] | Promise<GetStaticPathsItem[]>

You should use this function if you plan to use any translation features inside a getStaticPaths. This is to fix some Astro behaviour. Using the t function is not recommended inside getStaticPaths.

`t`

Alias for astroI18n.t.

`l`

Alias for astroI18n.l.

`astroI18n.environment`

environment: "node" | "none" | "browser"

The current detected environment.

`astroI18n.route`

route: string

The current route (without the locale, for example /fr/about will return /about).

`astroI18n.pages`

pages: string[]

An array of all the available pages. At the moment it only detects pages for which you have a translation (even if it's empty).

`astroI18n.page`

page: string

The corresponding page for the current route, for example /posts/my-cool-slug will be /posts/[slug]. Only gets detected if you have a translation for that page (even if it's empty).

`astroI18n.locale`

locale: string

The locale for the current page.

`astroI18n.locales`

locales: string[]

All the supported locales.

`astroI18n.primaryLocale`

primaryLocale: string

The configured primary locale.

`astroI18n.secondaryLocales`

secondaryLocales: string

The configured secondary locales.

`astroI18n.fallbackLocale`

fallbackLocale: string

The configured fallback locale.

`astroI18n.isInitialized`

isInitialized: boolean

True once the config has been loaded and the state initialized.

`astroI18n.t`

function t(
	key: string,
	properties?: Record<string, unknown>,
	options?: {
		route?: string
		locale?: string
		fallbackLocale?: string
	},
): string

The main translation function (t is an alias).

`astroI18n.l`

function l(
	route: string,
	parameters?: Record<string, unknown>,
	options?: {
		targetLocale?: string
		routeLocale?: string
		showPrimaryLocale?: boolean
		query?: Record<string, unknown>
	},
): string

The main routing function (l is an alias).

`astroI18n.addTranslations`

function addTranslations(translations: {
	[group: string]: {
		[locale: string]: DeepStringRecord
	}
}): AstroI18n

Adds new translations at runtime.

`astroI18n.addFormatters`

function addFormatters(formatters: {
	[name: string]: (value: unknown, ...args: unknown[]) => unknown
}): AstroI18n

Adds new formatters at runtime.

`astroI18n.addTranslationLoadingRules`

function addTranslationLoadingRules(
	translationLoadingRules: {
		groups: string[]
		routes: string[]
	}[],
): AstroI18n

Adds new translation loading rules at runtime.

`astroI18n.addRoutes`

function addRoutes(routes: {
	[secondaryLocale: string]: {
		[segment: string]: string
	}
}): AstroI18n

Adds new route segment translations at runtime.

`astroI18n.extractRouteLocale`

function extractRouteLocale(route: string): string

Utility function to parse one of the configured locales out of the given route.

`astroI18n.redirect`

function redirect(destination: string | URL, status = 301): void

Use this instead of Astro.redirect to redirect users.

Components

You can use these premade components in your project :

HrefLangs

SEO component, see hreflang.

---
import { astroI18n } from "astro-i18n"

const params: Record<string, string> = {}
for (const [key, value] of Object.entries(Astro.params)) {
	if (value === undefined) continue
	params[key] = String(value)
}

const hrefLangs = astroI18n.locales.map((locale) => ({
	href:
		Astro.url.origin +
		astroI18n.l(Astro.url.pathname, params, {
			targetLocale: locale,
		}),
	hreflang: locale,
}))
---

{
	hrefLangs.map(({ href, hreflang }) => (
		<link rel="alternate" href={href} hreflang={hreflang} />
	))
}

LocaleSwitcher

Simple component to switch locales.

---
import { astroI18n, l } from "astro-i18n"

interface Props {
	showCurrent: boolean
	labels: {
		[locale: string]: string
	}
}

const { showCurrent = true, labels = {} } = Astro.props

const params: Record<string, string> = {}
for (const [key, value] of Object.entries(Astro.params)) {
	if (value === undefined) continue
	params[key] = String(value)
}

let links = astroI18n.locales.map((locale) => ({
	locale,
	href: l(Astro.url.pathname, params, {
		targetLocale: locale,
	}),
	label: labels[locale] || locale.toUpperCase(),
}))

if (!showCurrent) {
	links = links.filter((link) => link.locale !== astroI18n.locale)
}
---

<nav>
	<ul>
		{
			links.map(({ href, label }) => (
				<li>
					<a href={href}>{label}</a>
				</li>
			))
		}
	</ul>
</nav>

CLI

`astro-i18n install`

Generates default files and add i18n commands to package.json.

`astro-i18n generate:pages`

Generates the pages corresponding to your current config and src/pages folder. You can use the --purge argument to clear old pages.

`astro-i18n generate:types`

Generates types in src/env.d.ts to give you type safety according to your config & translations.

`astro-i18n extract:keys`

Extract all the translation keys used in src/pages (as long as they are strings and not variables), and adds them to your i18n folder for every locale. This is useful if you use your keys as values.

Name		Name	Last commit message	Last commit date
Latest commit History 161 Commits
.github		.github
apps/astro		apps/astro
astro-i18n		astro-i18n
img		img
.eslintignore		.eslintignore
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
.npmrc		.npmrc
.prettierrc.cjs		.prettierrc.cjs
LICENCE		LICENCE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
turbo.json		turbo.json

License

Alexandre-Fernandez/astro-i18n

Folders and files

Latest commit

History

Repository files navigation

astro-i18n

Features

Introduction

Installation

Get started

Configuration

primaryLocale

secondaryLocales

fallbackLocale

showPrimaryLocale

trailingSlash

run

translations

translationLoadingRules

translationDirectory

routes

Variants

Interpolations

Interpolation formatters

Reference

defineAstroI18nConfig

useAstroI18n

createGetStaticPaths

t

l

astroI18n.environment

astroI18n.route

astroI18n.pages

astroI18n.page

astroI18n.locale

astroI18n.locales

astroI18n.primaryLocale

astroI18n.secondaryLocales

astroI18n.fallbackLocale

astroI18n.isInitialized

astroI18n.t

astroI18n.l

astroI18n.addTranslations

astroI18n.addFormatters

astroI18n.addTranslationLoadingRules

astroI18n.addRoutes

astroI18n.extractRouteLocale

astroI18n.redirect