astro-i18n

Variants allow you to handle plurals and context within a single translation key using a specific syntax: key{{ variable: value }}.

Plurals: Numbers will match the closest value. Context: Use non-numeric values to match specific contexts.

{
  "car": "There is a car.",
  "car{{ cars: 2 }}": "There are two cars.",
  "context{{ weather: 'rain' }}": "It's rainy."
}

import { t } from "astro-i18n"

t("car", { cars: 2 }) // "There are two cars."
t("context", { weather: "rain" }) // "It's rainy."

Translations in astro-i18n are organized into groups. This allows for efficient loading and scoping of data:

• "common" group: Accessible on every page.
• Current page group: Named after the route (e.g., "/about"). Only accessible on that specific page.
• Custom groups: Named by you (e.g., "admin"). You decide which pages can access them using translationLoadingRules.
• Route groups: If a group name matches a route (e.g., "/posts/[id]"), it loads automatically on that page.

Priority/Specificity: If duplicate keys exist across groups, the t function returns the most specific one in this order: Custom group $\rightarrow$ Local page group $\rightarrow$ Common group.

// Example of a custom group in config
const translations = {
  "common": { "en": { "hello": "Hello" } },
  "admin": { "en": { "welcome": "Admin Welcome" } }
};

You can store translations in several locations:

1. Inside the middleware config.
2. In a root config file (astro-i18n.config.(ts|js|cjs|mjs|json)).
3. In src/pages (local page translations).
4. In the src/i18n directory (custom groups).

File Naming Conventions: Local page translations can be placed in src/pages or src/i18n/pages (nested like Astro routes). Valid formats include:

• fr.json (Regular)
• _fr.json (Private)
• fr.translated-page-name.json (Regular with translation)
• _fr.translated-page-name.json (Private with translation)

Custom Groups: Create a directory in src/i18n named after your group. Use translationLoadingRules in your config to specify which routes should load these groups.

// Example translation file: src/pages/about/_i18n/fr.a-propos.json
{
  "my_nested": {
    "translation_key": "bonjour"
  }
}

You can install astro-i18n using your preferred package manager:

# npm
npm install astro-i18n

# yarn
yarn add astro-i18n

# pnpm
pnpm add astro-i18n

To achieve full TypeScript type-safety and autocompletion for your translations, and to generate your translated routes, run the following command:

npm run i18n:sync

To quickly set up the project, run the install command. This will generate the necessary configuration files and middleware.

If you are deploying to a serverless environment (where you have no filesystem or Node.js setup), use the --serverless flag. In serverless mode, all initial data must be passed directly to the middleware.

After installation, ensure your middleware file (src/middleware.ts or src/middleware/index.ts) uses useAstroI18n:

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

// Pass your config and custom formatters here
const astroI18n = useAstroI18n()

export const onRequest = sequence(astroI18n)

./node_modules/.bin/astro-i18n install
# For serverless environments:
./node_modules/.bin/astro-i18n install --serverless

The translations object allows you to define localized strings. You can organize translations in two ways:

1. Global/Common Scope: Using a key like common to provide translations accessible across the entire application.
2. Route-based Scope: Defining translations specific to a path (e.g., /page or /page/[id]) or a group.

Within each scope, keys are mapped to specific locales (e.g., en, fr). The system supports complex keys for variants (using ICU-like syntax), nested objects, and interpolation.

translations: {
  common: {
    en: {
      key: "value",
      "variant{{ n: 2 }}": "value for n=2"
    },
    fr: {
      key: "valeur"
    }
  },
  "/page": {
    en: {
      title: "Page Title"
    }
  }
}

The useAstroI18n function is the mandatory middleware required to make the library work. It accepts a configuration object (or a string path to a config file) and an optional object of custom formatters.

Signature: useAstroI18n(config?: Partial<AstroI18nConfig> | string, formatters?: { [name: string]: (value: unknown, ...args: unknown[]) => unknown }): AstroMiddleware

import { useAstroI18n } from "astro-i18n";

// Using a config object
export default useAstroI18n({
  primaryLocale: 'en',
  secondaryLocales: ['fr', 'es'],
});

The t function is used to retrieve translation values by key. It supports nested keys using dot notation.

import { t } from "astro-i18n"

// Returns the value for the key
t("my_nested.translation_key")