Overview

Internationalization lets you offer the same product in multiple languages. Edge Kit uses Paraglide, which turns your translation catalogs into type-safe messages for React and server code.

The language setup already connects routing, React copy, validation, authentication messages, and emails. You can change your product's text or add languages through shared catalogs, with generated types keeping usage consistent across the application.

English and Spanish provide the starting translations and language-switching experience. Build on the same setup for the markets your product serves.

Language detection

Localized URLs (like /en or /es) select their language directly. For an unprefixed app URL, the saved language preference and browser language help choose the locale, with English as the default.

The language switcher changes the current locale without requiring a separate copy of every page. Routing and server rendering use the same language configuration.

Translations

Message catalogs hold your UI and email text. Components use generated messages instead of hard-coded strings:

import { m } from "@/lib/i18n/messages.js";

<span>{m.save()}</span>;

The kit's lint rules encourage translated visible text and accessibility labels. Dates, validation errors, and authentication messages also have locale support.

Formatting and parameters

A translated interface needs more than a word-for-word copy of its labels. Dates, counts, plurals, and dynamic values should read naturally in the customer's language.

Use message parameters for values such as a customer's name or a resource count, keeping the same parameters in each translation. Prefer a complete translated sentence over joining several short fragments, since word order can change between languages.

The kit connects locale dictionaries for validation and date handling. When adding another language, extend those dictionaries alongside the app messages so an otherwise translated form does not fall back to errors in a different language.

Request context

The page's language and a later background job's language have different lifecycles. Routing can resolve the locale for the current browser request. A delayed notification needs the recipient's language supplied with the work or loaded from product data.

Follow the existing auth and email flows when passing locale information between those boundaries. For a new server integration, decide whether its language follows the current request or a saved customer preference.

Emails and content

Emails carry an explicit language, so a background job can send a translated message after the original request has finished.

Blog posts and legal pages use separate localized MDX files. They share the same slug across languages and can fall back to the default language when a translation is missing.

The guides below cover message catalogs, language selection, and additional languages.

Localized experience

Check direct page loads, language switching, and browser back navigation together. Review long labels in menus and buttons, form errors, empty states, and email subjects as well as the main page copy.

For public content, keep equivalent articles under the same slug and review the localized links generated for search discovery. An available fallback is useful for missing content, but publishing a translated article also needs its own accurate title, summary, and body.