Internationalization

On This Page

Two Locale Strategies

SyntaxKit uses next-intl with two strategies:

apps/web/proxy.ts decides which strategy applies for each request.

URL prefix for marketing. Search engines need a stable URL per language. Shares should open in that language. /en/pricing and /de/pricing are different pages in the index. The URL is the source of truth.

Cookie for the dashboard. A shared link like /dashboard/billing/invoices/inv_123 must work for every teammate, regardless of language. The path stays fixed. Locale follows the user via the cookie.

Package Layout

i18n spans three places:

• packages/i18n: shared registry and path helpers (both apps import these)
• apps/web/i18n: next-intl wiring for the product app
• apps/web/messages: translation catalogs

Locale registry

Two locales today (en, de). Default is en. Both apps import this registry:

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",
};

@syntaxkit/i18n helpers fall into two groups:

• Locale checks: isValidLocale, normalizeLocale
• Path builders: withLocalePrefix, getLoginPath, getSignupPath, and the other auth/onboarding helpers

proxy.ts uses the path builders when redirecting legacy unprefixed entry points (e.g. /auth/login → /<locale>/auth/login).

How A Request Routes

apps/web/proxy.ts has five branches. Each picks locale differently:

Dashboard requests skip next-intl middleware on purpose. The URL does not carry locale there; request.ts reads the cookie at render time. If next-intl ran on those routes, it would try to inject /en/... prefixes into paths that must stay unprefixed.

Translating Content

Pick a namespace (a top-level key in the JSON), get a translator, call it with keys. Same pattern on client and server.

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 at apps/web/messages/<locale>.json. Namespaces are nested top-level keys (Header, Auth.login, Settings.language, and so on). apps/web/global.d.ts types messages from en.json, so missing keys in other locales fail the type check at build time.

Switching Locales

Both switchers call the same setLocale server action and write the same NEXT_LOCALE cookie. They differ only in what happens to the URL.

• Marketing (locale-switcher.tsx in the header). Writes the cookie, then router.replace to the same path under the new /<locale>/ prefix. The cookie carries the choice into the dashboard after sign-in.
• Dashboard (user-locale-form.tsx in personal settings). Writes the cookie, then router.refresh(). The URL stays at /dashboard/personal-settings.

Pick German on the marketing header, sign in, and the dashboard opens in German. The cookie was already set.

The NEXT_LOCALE cookie

This cookie powers the dashboard strategy. setLocale in apps/web/i18n/actions.ts writes it with:

Three consumers read it:

The cookie is the live preference. Logged-in users also persist it to User.locale for surfaces with no request.

User.locale fallback

Some work has no request cookie: welcome emails from a Better Auth DB hook, Stripe webhooks, invitations to people without a session. For those, signed-in users store locale in a nullable User.locale column.

See Email → Localization for the full resolution flow.

Adding A New Locale

Where To Go Next

Also useful: API, Conventions, and Setup.