AddThisFeature

Locale and Language Switcher

Let people change language without losing their place or seeing half a translation.

involved Accessibility & Internationalization

What it adds

A locale selector wired into routing and persistence, with sane fallbacks when a translation is missing.

What your agent is told to do

6
  1. 1

    Decide how locale is carried before building the switcher: a URL path segment, a subdomain, or a stored preference. The URL is the only one that survives sharing and indexing.

  2. 2

    Resolve the active locale in a fixed order — explicit URL, saved user preference, Accept-Language header, then default — and apply the same order on the server and the client.

  3. 3

    Switching must land the user on the equivalent page in the new locale, not on the home page.

  4. 4

    Fall back per key to the default locale when a translation is missing, and log the miss so it can be filled. Never render a raw key like users.profile.title to a person.

  5. 5

    Set the document language and direction attributes from the active locale, and support right-to-left layout where a supported locale requires it.

  6. 6

    Do NOT infer the language from IP geolocation. Country is not language, and overriding an explicit choice with a guess is worse than showing the default.

Edge cases it handles

7
  • The server-rendered locale must match what the client resolves, or hydration mismatches will flash the wrong language.
  • A saved preference must not silently override an explicit locale in the URL — the URL wins, and it should update the saved preference.
  • An entire missing locale should degrade to the default cleanly rather than producing a page of empty strings.
  • Pluralization rules differ by language; a two-form English rule breaks in locales with more forms.
  • User-generated content is not translated. Do not run it through the translation layer or label it with the interface locale.
  • Right-to-left flips layout, icons with direction, and scroll position — mirroring the text alone leaves a broken page.
  • Emails, PDFs, and other out-of-band output need the recipient's stored locale, not the locale of whoever triggered them.

Definition of done

9
  • Locale resolution follows one documented order on both server and client.
  • Switching language keeps the user on the equivalent route.
  • The choice persists across sessions but never overrides an explicit URL locale.
  • Missing keys fall back to the default locale and are logged; no raw keys are ever rendered.
  • There is no hydration mismatch or flash of the wrong language.
  • Document language and direction attributes reflect the active locale, and RTL layouts are correct.
  • Emails and generated documents use the recipient's locale.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.