Localization Overview

StarterApp ships with an opt-in localization system powered by @starterapp/i18n-core and @starterapp/i18n-next. The default marketing experience (including /) stays English-only, but you can opt specific routes into localization—see /localized-page-example for a working sample.

Quick Start

1. Import the shared preset. apps/marketing/i18n.ts already calls createLocalizedExampleAppI18n("marketing"), which registers English + Spanish dictionaries and opt-ins /localized-page-example.

2. Opt a route into localization. Use the exported marketingRoutes registry:

   marketingRoutes.register("/my-localized-route");

   When you need a bespoke dictionary, call createAppI18n or build a helper similar to the packaged example and reuse it across apps.

3. Wrap the page export with createMarketingLocalizedPage so the provider and message loading are handled for you. See Adding a Localized Route for the full workflow:

   // app/(marketing)/example/page.tsx
   import { createMarketingLocalizedPage } from "~/i18n/server";
   
   export default createMarketingLocalizedPage({
     namespaces: ["example"],
     render: ({ locale, messages }) => {
       const t = createTranslator({ locale, messages, namespace: "example" });
       return <Page translations={t} />;
     },
   });

   The helper automatically loads common plus any additional namespaces, merges shared fallbacks, and wraps the result in StarterAppI18nProvider.

Routing Model

• Marketing home requests (/ or /<locale>) default to English; no provider is mounted there.
• Opt-in routes (for example /localized-page-example) use createMarketingLocalizedPage, which wires middleware negotiation, dictionary loading, and the provider automatically.
• Other marketing routes stay English-only unless you opt into localization using the same helper.
• Dashboard routes are explicitly English and do not participate in locale negotiation.

Testing & Telemetry

Adding a New Locale