TIP

This page mirrors .agents/i18n.md from the repository. Edit it at the source, not here.

i18n Guidelines

Copy Keys

Use the {FEATURE_OR_PAGE}__{...MORE_SPECIFIC_IDENTIFIERS} convention.

Examples:

• home_page__hero_title
• auth__sign_in_title
• navbar__dashboard

English-Only Default

Add new copy keys to packages/i18n/messages/en.json only by default. Do not edit de.json or any other non-English locale unless the user explicitly asks for translation work.

Translation is a separate agent workflow. Do not run machine translation or manually fill translated locale files as part of ordinary feature work.

Paraglide Codegen

If new or renamed keys need generated Paraglide modules for typecheck or runtime, run:

vp run --filter @saasweave/i18n build

This is codegen, not translation.

Gotchas

• Do not call m.*() at module scope for labels, route config, nav config, or other long-lived objects. Store a function and resolve the translated string during render or request handling so SSR and hydration use the same locale.
• For the current {-$locale} routing model, the URL is the source of truth: non-base locales use a path prefix and the base locale is unprefixed. Do not add cookie or preferred-language strategies ahead of baseLocale, because / must hydrate deterministically as the base locale.
• Language switching should navigate to the localized URL through the TanStack Start i18n provider instead of calling Paraglide setLocale() directly from UI components.