For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/modules/i18n.md (or send Accept: text/markdown).

i18n module

The locale contract every surface shares.

Ask about this guide

Before you begin

Open your downloaded supastack project in Visual Studio Code using File → Open Folder, then choose Terminal → New Terminal. The repository root is the folder containing package.json, apps and packages. Run the command below there and leave its terminal open. If a command is not recognized, finish the tool installation guide before continuing.

Read the platform tutorial first. A server is the app process that answers browser or phone requests. Web reads apps/web/.env.local, Expo reads apps/mobile/.env.local, and database migration commands read root .env. The no-database /dashboard demonstration is separate from real /auth accounts, which need migrated Postgres. A phone or desktop-only checkout needs a separately running Web backend.

corepack pnpm --filter @supastack/web dev

Setup and configuration

packages/i18n owns the locale set and resolution contract: SUPPORTED_LOCALES, DEFAULT_LOCALE, LOCALE_COOKIE, isAppLocale, resolveLocale, localePath, and getDictionary. Web routes, mobile strings, and transactional mail all read through the same package.

Resolution order is path prefix → cookie → Accept-Language → default. localePath(locale, path) produces the canonical href — un-prefixed for the default locale, /{locale}/… otherwise — and the proxy layer enforces it.

import { getDictionary, localePath, resolveLocale } from "@supastack/i18n";

const locale = resolveLocale([pathLocale, cookie, acceptLanguage]);
const copy = getDictionary(locale).marketing;

Implementation workflow

Add a user-facing string to the dictionary types first, then every locale — the translation completeness suite fails on missing keys and on English text left untranslated.

Never branch product logic on locale; dictionaries are presentation. Format dates, numbers, and plurals through Intl APIs with the resolved locale rather than string templates.

Verification and troubleshooting

Run the i18n package tests plus the site-content completeness suite after touching keys. Spot-check a locale-prefixed route, the language switcher, and Accept-Language detection with a cleared cookie.