Internationalization

SyntaxKit's i18n is built on next-intl, but it doesn't use one routing strategy. It uses two, deliberately. Public marketing and auth pages live under /[locale]/... with the locale in the URL for SEO and shareability; the dashboard stays at /dashboard/... and gets its locale from a NEXT_LOCALE cookie so deep links don't depend on the user's language. apps/web/proxy.ts is the foundation that makes both strategies coexist cleanly.

Two Locale Strategies

Why URL-prefix for marketing. Search engines need stable canonical URLs per language, social shares need to land in the right language, and /en/pricing and /de/pricing are two different things in Google's index. The URL is the source of truth.

Why cookie for dashboard. A user shares /dashboard/billing/invoices/inv_123 with a teammate; the teammate shouldn't get a 404 because their preference is German and the link said /en/.... URLs stay stable, locale follows the user.

The diagram source lives at apps/docs/diagrams/locale-routing.mmd. Rerun pnpm --filter @syntaxkit/docs diagrams:build after editing it to refresh both SVG variants.

Package Layout

The i18n logic lives across three locations on purpose. packages/i18n owns the registry and path helpers so both apps can share them. apps/web/i18n owns the next-intl wiring specific to the product app. apps/web/messages is the translation catalog.

Locale Registry

Two locales today (en, de), default en. The registry is a small file that both apps import:

export const locales = ["en", "de"] as const;
export type Locale = (typeof locales)[number];

export const defaultLocale: Locale = "en";

export const localeLabels: Record<Locale, string> = {
  en: "English",
  de: "Deutsch",
};

Helpers exported from @syntaxkit/i18n split into two groups: locale validation (isValidLocale, normalizeLocale) and path builders (withLocalePrefix, getLoginPath, getSignupPath, getForgotPasswordPath, getResetPasswordPath, getVerifyEmailPath, getTwoFactorVerifyPath, getAcceptInvitationPath, getCreateOrganizationPath). The path builders are what proxy.ts uses to build redirect URLs for legacy unprefixed entry points like /auth/login → /<locale>/auth/login.

How A Request Routes

Five branches in apps/web/proxy.ts, each handling locale differently:

The dashboard branch deliberately skips next-intl's middleware because the URL has nothing to do with the locale there; the locale comes from the cookie at render time inside request.ts. If next-intl ran on dashboard requests it would try to inject /en/... prefixes into routes it shouldn't touch.

Translating Content

Both client and server components translate the same way: pick a namespace (top-level key in the JSON), get the translator, call it with keys.

Client components use useTranslations:

"use client";
import { useTranslations } from "next-intl";

export function HeaderActions() {
  const t = useTranslations("Header");
  return <button>{t("signIn")}</button>;
}

Server components use getTranslations:

import { getTranslations } from "next-intl/server";

export default async function NotFound() {
  const t = await getTranslations("errors.notFound");
  return <h1>{t("title")}</h1>;
}

Messages live in a single JSON per locale at apps/web/messages/<locale>.json. Namespaces are nested top-level keys (Header, Auth.login, Settings.language, etc.). The apps/web/global.d.ts declaration tells TypeScript to use en.json as the canonical message shape, so missing keys in any other locale surface as type errors at build time.

Switching Locales

Two switchers, both writing the same cookie through the setLocale server action. The only difference is whether the URL changes.

A user who picks German on the marketing header lands in a German dashboard after signing in, because the cookie was set before the redirect.

The NEXT_LOCALE Cookie

Powers the dashboard half of the design. Written by the setLocale server action (apps/web/i18n/actions.ts) with these attributes:

It's read in three places:

The cookie is the source of truth for the current preference; logged-in users also persist it to User.locale for surfaces that have no request.

User.locale: The Out-Of-Band Fallback

The cookie is useless for surfaces with no request: the welcome email fires from a Better Auth DB hook, Stripe webhooks carry no end-user context, and invitations go to people without a session. So signed-in users persist their locale to a nullable User.locale column.

See Email → Localization for the full resolution flow.

Adding A New Locale

Where To Go Next