# Internationalization (i18n) — Xertica UI Xertica UI projects use **`i18next`** with the **`react-i18next`** binding for all UI string translations. The `LanguageSelector` component is wired directly to `i18next` — changing the language immediately updates every `useTranslation()` consumer in the app and invalidates the React Query cache so that data-layer strings (mock API responses) also refresh. --- ## Setup ### 1. Install ```bash npm install i18next react-i18next ``` Both packages are listed in `templates/package.json` and are installed automatically by `npx xertica-ui@latest init`. ### 2. Create locale files Locales are organized as one **folder per language**, split by category: ``` src/locales/ ├── .languages.json ← CLI-managed selection ({ "version": 1, "codes": [...] }) ├── pt-BR/ ← default & fallback (only your selected languages are present) │ ├── common.json ← shared action labels (view, edit, save, cancel…) │ ├── nav.json ← navigation labels │ ├── errors.json ← error boundary UI │ ├── languageSelector.json ← language picker UI │ ├── themeToggle.json ← theme toggle UI │ ├── pages/ │ │ ├── home.json │ │ ├── templates.json │ │ ├── login.json │ │ ├── resetPassword.json │ │ ├── verifyEmail.json │ │ ├── loginTemplate.json ← starter template pages │ │ ├── formTemplate.json │ │ ├── dashboardTemplate.json │ │ └── crudTemplate.json │ └── components/ │ ├── assistant.json │ ├── sidebar.json │ ├── media.json │ ├── projectCard.json │ ├── profileCard.json │ ├── notificationCard.json │ ├── activityCard.json │ ├── stats.json │ └── team.json ├── en/ ← same structure └── es/ ← same structure ``` Each JSON file contains only the keys for its category (no top-level wrapper key). For example, `locales/pt-BR/common.json`: ```json { "view": "Visualizar", "edit": "Editar", "loading": "Carregando...", "cancel": "Cancelar" } ``` And `locales/pt-BR/pages/home.json`: ```json { "welcome": "Bem-vindo ao Design System!", "subtitle": "...", "templateCliTitle": "Template CLI" } ``` > All files under `locales//` are automatically discovered by `import.meta.glob` in `i18n.ts`. Adding a new JSON file requires no changes to `i18n.ts` — Vite picks it up on the next build. ### 3. Create `src/i18n.ts` ```ts import i18n from 'i18next'; import { initReactI18next } from 'react-i18next'; // Merges the split JSON files (pages/, components/) into one flat bundle per language. // The key is the file basename — folder (pages/components) is discarded. // Adding a new JSON file under locales//... is auto-discovered by Vite. function bundleLang(chunks: Record): Record { const out: Record = {}; for (const [filePath, value] of Object.entries(chunks)) { const base = filePath.split('/').pop(); if (!base) continue; out[base.replace(/\.json$/, '')] = value; } return out; } // `import.meta.glob` requires a literal pattern — one call per language. // `eager: true` inlines the JSON at build time (no runtime fetch). const ptBR = bundleLang( import.meta.glob('./locales/pt-BR/**/*.json', { eager: true, import: 'default' }) ); const en = bundleLang( import.meta.glob('./locales/en/**/*.json', { eager: true, import: 'default' }) ); const es = bundleLang( import.meta.glob('./locales/es/**/*.json', { eager: true, import: 'default' }) ); const savedLanguage = typeof window !== 'undefined' ? (localStorage.getItem('xertica_language') ?? 'pt-BR') : 'pt-BR'; i18n.use(initReactI18next).init({ resources: { 'pt-BR': { translation: ptBR }, en: { translation: en }, es: { translation: es }, }, lng: savedLanguage, fallbackLng: 'pt-BR', interpolation: { escapeValue: false }, // React escapes already }); export default i18n; ``` ### 4. Initialize before rendering ```ts // src/main.tsx — BEFORE any component import import './i18n'; // side-effect: initializes i18next synchronously import App from './app/App'; ``` --- ## Using Translations in Components ```tsx import { useTranslation } from 'react-i18next'; function HomeContent() { const { t } = useTranslation(); return (

{t('home.welcome')}

{t('home.subtitle')}

); } ``` ### Interpolation ```json { "team": { "showing": "Exibindo {{count}} de {{total}} usuários" } } ``` ```tsx t('team.showing', { count: 5, total: 127 }); // → "Exibindo 5 de 127 usuários" ``` --- ## Language Switching The `LanguageSelector` component (from `xertica-ui/brand`) handles the full switching flow automatically: 1. User selects a language in the dropdown 2. `setLanguage(lang)` is called on `LanguageContext` 3. `LanguageContext` writes to `localStorage` (key: `xertica_language`) and calls `i18n.changeLanguage(lang)` 4. All components using `useTranslation()` re-render with the new locale 5. `queryClient.invalidateQueries()` is called — React Query refetches any query whose result contains translated strings ```tsx // Manual language change (without LanguageSelector) import { useLanguage } from 'xertica-ui/hooks'; const { setLanguage } = useLanguage(); setLanguage('en'); // persists + calls i18n.changeLanguage('en') + invalidates React Query cache ``` ### Language codes | Code | Display | Stored as | | --------- | -------------- | --------------------------- | | `'pt-BR'` | Português (BR) | `'pt-BR'` in `localStorage` | | `'en'` | English | `'en'` | | `'es'` | Español | `'es'` | --- ## Translation Key Namespaces The project uses a single `translation` namespace. Each top-level key maps to a separate JSON file under `locales//`: **Root files** (`locales//.json`): | Namespace | File | Example keys | | ------------------ | ----------------------- | ------------------------------------------------------------------------------- | | `common` | `common.json` | `common.view`, `common.edit`, `common.loading`, `common.close`, `common.copied` | | `nav` | `nav.json` | `nav.home`, `nav.designSystem`, `nav.settings` | | `errors` | `errors.json` | `errors.somethingWentWrong`, `errors.tryAgain`, `errors.pageLoadError` | | `languageSelector` | `languageSelector.json` | `languageSelector.label`, `languageSelector.ptBR` | | `themeToggle` | `themeToggle.json` | `themeToggle.switchToLight`, `themeToggle.darkMode` | **Page files** (`locales//pages/.json`): | Namespace | File | Example keys | | ------------------- | ------------------------------ | --------------------------------------------------------------------------------- | | `home` | `pages/home.json` | `home.welcome`, `home.subtitle`, `home.templateCliTitle` | | `templates` | `pages/templates.json` | `templates.title`, `templates.alerts.infoTitle`, `templates.forms.firstName` | | `login` | `pages/login.json` | `login.heading`, `login.submit`, `login.forgotPassword` | | `resetPassword` | `pages/resetPassword.json` | `resetPassword.heading`, `resetPassword.errorMismatch` | | `verifyEmail` | `pages/verifyEmail.json` | `verifyEmail.heading`, `verifyEmail.resend` | | `loginTemplate` | `pages/loginTemplate.json` | `loginTemplate.title`, `loginTemplate.submit` | | `formTemplate` | `pages/formTemplate.json` | `formTemplate.title`, `formTemplate.save`, `formTemplate.errors.fullNameRequired` | | `dashboardTemplate` | `pages/dashboardTemplate.json` | `dashboardTemplate.title`, `dashboardTemplate.stats.totalRevenue` | | `crudTemplate` | `pages/crudTemplate.json` | `crudTemplate.title`, `crudTemplate.actions.editProfile` | **Component files** (`locales//components/.json`): | Namespace | File | Example keys | | ------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------------------- | | `assistant` | `components/assistant.json` | `assistant.title`, `assistant.inputPlaceholder`, `assistant.tabs.chat`, `assistant.feedbackDialog.title` | | `sidebar` | `components/sidebar.json` | `sidebar.collapse`, `sidebar.logout`, `sidebar.moreOptions` | | `media` | `components/media.json` | `media.play`, `media.pause`, `media.downloadAudio`, `media.floatingMode` | | `projectCard` | `components/projectCard.json` | `projectCard.progress`, `projectCard.status.active` | | `profileCard` | `components/profileCard.json` | `profileCard.status.online`, `profileCard.status.busy` | | `notificationCard` | `components/notificationCard.json` | `notificationCard.title`, `notificationCard.markAllRead` | | `activityCard` | `components/activityCard.json` | `activityCard.title`, `activityCard.type.create` | | `stats` | `components/stats.json` | `stats.totalUsers`, `stats.last30Days` | | `team` | `components/team.json` | `team.name`, `team.roles.Developer`, `team.showing` | --- ## Translating Mock Data Mock data fetch functions use `i18n.t()` (the instance, not the hook) so they respond to the active language when called from a React Query `queryFn`: ```ts // features/home/data/mock.ts import i18n from '../../../i18n'; export async function fetchFeatureCards(): Promise { return [ { id: 'template-cli', title: i18n.t('home.templateCliTitle'), // ← translated at query time description: i18n.t('home.templateCliDescription'), }, ]; } ``` ### Language-aware React Query Keys Every hook that returns translated strings includes the active language in its `queryKey` so that each locale gets its own cache slot and switches instantly without a page reload: ```ts // features/home/hooks/useFeatureCards.ts import { useLanguage } from 'xertica-ui/hooks'; export function useFeatureCards() { const { language } = useLanguage(); return useQuery({ queryKey: ['home', 'feature-cards', language], // ← language as third element queryFn: fetchFeatureCards, staleTime: 10 * 60 * 1000, }); } ``` **Why this works:** - Switching from `pt-BR` → `en` changes the queryKey to `['home', 'feature-cards', 'en']` - React Query finds no cache entry for this key → triggers an immediate refetch - `fetchFeatureCards()` runs again → `i18n.t()` now returns English strings - Switching back to `pt-BR` → cache hit (Portuguese data still stored) → instant, no refetch The `setLanguage()` call in `LanguageContext` also calls `queryClient.invalidateQueries()` as a defensive backstop for any query not yet updated to include `language` in its key. ### Fallback factory functions (not frozen constants) When you need static fallback data while a query loads, use **factory functions** (not `const` arrays): ```ts // ✅ Correct — evaluated at call time, always returns current language export function getMockRichSuggestions(): Suggestion[] { return [{ id: 'rich-1', text: i18n.t('assistant.richSuggestions.viewPerformance') }]; } // ❌ Wrong — i18n.t() runs once at module load, frozen in initial language export const MOCK_RICH_SUGGESTIONS = [ { id: 'rich-1', text: i18n.t('assistant.richSuggestions.viewPerformance') }, ]; ``` ```tsx // Usage in component richSuggestions={assistantConfig?.richSuggestions ?? getMockRichSuggestions()} ``` --- ## Configuring Available Languages The set of languages a project supports is configured **at runtime** via the `availableLanguages` prop on `` (or ``). The library ships with built-in support for `pt-BR`, `en`, and `es` (exposed as `DEFAULT_LANGUAGES`), but the system is fully extensible. ### Choosing languages via the CLI When you scaffold a new project, the CLI asks you which languages to enable: ```bash $ npx xertica-ui init my-app ✔ Which pages/templates to include? › Login, Home, Template ✔ Which languages should the app support? › Português (BR), English, Español ✔ Select the default color theme: › Xertica ``` Pick **all three** (default), **two**, or **just one**: - **All three** — the CLI omits the `availableLanguages` prop entirely (the library default already matches). - **Two or one** — the CLI injects the explicit `availableLanguages` array into `src/app/App.tsx`. - **Just one (monolingual)** — additionally, the `LanguageSelector` auto-hides because there is nothing to switch between. A header banner comment in `App.tsx` documents this. The CLI also: - Copies **only** the locale **folders** for the selected languages into `src/locales/` (no orphan files). Each language is a directory tree with split JSON files. - Generates `src/i18n.ts` with `import.meta.glob` calls for exactly those languages — Vite auto-discovers all JSON files in the folder at build time. - Persists the selection in `src/locales/.languages.json` so the `update` command can preserve it. ### Adding or removing languages later Run `npx xertica-ui update` and choose **Languages**: ```bash $ npx xertica-ui update ✔ What do you want to update? › Languages Current languages: Português (BR), English ✔ Select the languages this project should support: › Português (BR), English, Español + es ⚠️ This will regenerate src/app/App.tsx and src/i18n.ts (preserving language-only changes). Continue? › yes ✔ Languages updated successfully! Copied: es/ ``` The command: 1. Computes the add/remove diff and shows it to you. 2. Copies the newly-added locale **folders** from `node_modules/xertica-ui/templates/src/locales//`. 3. Removes the **folders** of unselected languages from your project (also removes any legacy flat `.json` files if upgrading from pre-2.2.0). 4. Regenerates `src/i18n.ts` and `src/app/App.tsx` to reflect the new set. 5. Updates `src/locales/.languages.json`. > The `update` → **Project files** flow also reads `.languages.json` and preserves your selection — updating `App.tsx` and `i18n.ts` won't reset your languages to the defaults. ### Default — three built-in languages When you don't pass `availableLanguages`, the provider uses `DEFAULT_LANGUAGES`: ```tsx import { XerticaProvider } from 'xertica-ui'; {/* pt-BR, en, es are all available — selector shows all three */} ; ``` ### Monolingual — single language, no selector Pass a single-element array to lock the app to one language. The `LanguageSelector` component **auto-hides** because there is nothing to switch to: ```tsx {/* App is permanently English. LanguageSelector renders nothing. */} ``` To force the selector to render even when monolingual (e.g. for a future-proofing placeholder), pass ``. ### Adding a new language at runtime There are two ways to add a language without editing `src/i18n.ts`. **Option A — declarative, via `availableLanguages`** (recommended): ```tsx import { XerticaProvider, DEFAULT_LANGUAGES } from 'xertica-ui'; import fr from './locales/fr.json'; {/* French now appears in the selector; its strings are registered automatically */} ; ``` The provider calls `i18n.addResourceBundle()` on mount for any entry that carries `resources`. **Option B — imperative, via `registerLanguageResource`**: ```ts import { registerLanguageResource } from 'xertica-ui'; import fr from './locales/fr.json'; registerLanguageResource('fr', fr); // Then list it on the provider ``` ### Removing built-in languages Just omit them from `availableLanguages`. The translation bundles registered in `src/i18n.ts` remain loaded (they're cheap) but they're invisible to the UI: ```tsx {/* Only Portuguese and English appear — Spanish is hidden */} ``` ### Statically (library-only) — adding a built-in default Only used when contributing to the library itself, not for app consumers: 1. Create `locales//` folder mirroring an existing language (copy `locales/en/` as a starting point, then translate all values) 2. `i18n.ts` uses `import.meta.glob` — **no import changes needed**. Vite auto-discovers the new folder on the next build. 3. Add a `LanguageDefinition` entry to `DEFAULT_LANGUAGES` in `contexts/LanguageContext.tsx` 4. Add an entry to `SUPPORTED_LANGUAGES` in `bin/language-config.ts` so the CLI exposes it in its prompts 5. Mirror the same folder structure under `templates/src/locales//` for the scaffold template ### `LanguageDefinition` shape ```ts interface LanguageDefinition { /** BCP-47 language code stored in localStorage and passed to i18n.changeLanguage() */ code: string; /** Full display label shown in the LanguageSelector dropdown */ label: string; /** Short label shown in `variant="minimal"` (e.g. "PT", "EN"). Defaults to code.slice(0,2).toUpperCase() */ shortLabel?: string; /** Optional translation JSON. When provided, it is registered with i18next automatically. */ resources?: Record; } ``` ### `useLanguage()` extras ```ts const { language, // current locale code setLanguage, // change locale + persist + invalidate React Query availableLanguages, // LanguageDefinition[] currently configured isMonolingual, // true when availableLanguages.length === 1 } = useLanguage(); ``` --- ## AI Rules - **ALWAYS import `'./i18n'` in `main.tsx` before any component** — if omitted, `useTranslation()` falls back to returning the raw key string - **Use `t('namespace.key')` for all user-facing strings** — never hardcode text in JSX - **Use `i18n.t()` (the instance) in non-component code** (mock fetch functions, utility files) — `useTranslation()` is a hook and can only be called inside React components and custom hooks - **Include `language` in the `queryKey`** for every React Query hook that returns translated strings — this gives each locale its own cache slot and enables instant switching without reload - **Use factory functions, not frozen constants**, when you need pre-translated fallback arrays — `const arr = [i18n.t(...)]` evaluates once at module load and is permanently frozen - **Never hardcode language fallbacks in JSX** — add missing keys to the appropriate file under `locales//` instead - `setLanguage()` from `useLanguage()` is the single point of control — it persists to `localStorage`, calls `i18n.changeLanguage()`, and invalidates the React Query cache - Import `useLanguage` from `'xertica-ui/hooks'` (or directly from `'xertica-ui'`) — both resolve to the same export. The `xertica-ui/brand` subpath exports only the `LanguageSelector` component and `Language` type, NOT the `useLanguage` hook. - The `fallbackLng: 'pt-BR'` ensures missing keys in `en.json` or `es.json` display the Portuguese fallback instead of the raw key string - **The set of available languages is runtime-configurable** — pass `availableLanguages` to `` to add, remove, or restrict to a single locale. Never modify `DEFAULT_LANGUAGES` directly - **The `LanguageSelector` auto-hides when `isMonolingual` is true** — do not conditionally render it yourself; pass it `showWhenMonolingual` if you want it visible - **`Language` is typed as `string`** (not a strict union) to support runtime-added locales. Use `LanguageDefinition['code']` from `useLanguage().availableLanguages` for autocomplete