Internationalization

VibeKit includes complete internationalization (i18n) across the entire application stack. Powered by next-intl and a shared dictionary architecture in packages/i18n, your SaaS can welcome customers across the globe in their preferred languages without messy URL prefixes.

Worldwide Readiness Out of the Box

Launching in international markets increases conversion rates and reduces churn. VibeKit provides six production UI translation dictionaries ready to use:

• English (en): Default base language.
• German (de): Fully localized UI and documentation.
• Spanish (es): Complete Spanish UI dictionary.
• French (fr): Complete French UI dictionary.
• Japanese (ja): Japanese localized dictionary.
• Chinese (zh): Simplified Chinese localized dictionary.

All translations are strictly typed, ensuring that missing keys or mismatched string variables are caught during development and build time.

Seamless Cookie-Based Locale Switching

Many international websites clutter their URLs with locale prefixes (such as /en/dashboard or /de/dashboard), complicating link sharing, bookmarks, and server rewrites. VibeKit uses a cleaner approach:

1. Clean Canonical URLs: All routes stay clean and consistent (e.g., /dashboard or /pricing) regardless of the selected language.
2. Persistent Cookie Preference: The active language is saved in the NEXT_LOCALE HTTP cookie when the user selects a language from the interface.
3. Smart Header Detection: For first-time visitors who have not set a preference, VibeKit inspects the incoming Accept-Language browser header to automatically serve the most relevant available locale.
4. Header and Sidebar Switchers: Pre-built language dropdown components allow users to switch languages instantly without reloading the page.

Organized Dictionary Keys in packages/i18n

All UI copy is stored in clean, categorized JSON dictionaries under packages/i18n/translations/:

• common.json: Universal UI words like Save, Cancel, Delete, Confirm, Loading, and Error messages.
• auth.json: Sign-in, registration, password reset, and verification copy.
• navigation.json: Sidebar links, header items, and user menu labels.
• billing.json: Pricing tiers, plan descriptions, and invoice statuses.
• settings.json: Account, profile, and team management labels.

In your React components, accessing translated strings is straightforward with useTranslations():

import { useTranslations } from "next-intl";

export function WelcomeBanner() {
  const t = useTranslations("common");
  return <h1>{t("welcomeMessage")}</h1>;
}

Strict Translation Parity Guardrails

When adding new features or changing copy, it is easy to accidentally leave a key untranslated in other languages. VibeKit prevents runtime translation errors with automated checks:

• Key Parity Check: A verification script scans every dictionary file to confirm that every key in en.json exists in all other active languages.
• Variable Validation: The checker verifies that dynamic interpolation variables (such as {name} or {count}) are preserved across translations so strings do not break when rendered.
• Build Gate: Running bun run test or turbo check fails immediately if a translation dictionary is out of sync.

Working with Your Agent to Localize Features

Instruct your coding agent to add new language strings or translate new product features:

Add a new 'Export Data' modal to 'apps/web/features/export'.
Create the required translation keys under the 'export' namespace in 'packages/i18n/translations/en.json'.
Translate the new keys into German ('de.json') and Spanish ('es.json').
Run the translation verification check to ensure all dictionary keys match.