xertica-ui 2.2.1 → 2.4.0

package/docs/i18n.md

@@ -97,15 +97,13 @@ const es = bundleLang(
 );
 
 const savedLanguage =
-  typeof window !== 'undefined'
-    ? (localStorage.getItem('xertica_language') ?? 'pt-BR')
-    : 'pt-BR';
+  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 },
+    en: { translation: en },
+    es: { translation: es },
   },
   lng: savedLanguage,
   fallbackLng: 'pt-BR',
@@ -150,7 +148,7 @@ function HomeContent() {
 ```
 
 ```tsx
-t('team.showing', { count: 5, total: 127 })
+t('team.showing', { count: 5, total: 127 });
 // → "Exibindo 5 de 127 usuários"
 ```
 
@@ -176,11 +174,11 @@ setLanguage('en'); // persists + calls i18n.changeLanguage('en') + invalidates R
 
 ### Language codes
 
-| Code | Display | Stored as |
-|---|---|---|
+| Code      | Display        | Stored as                   |
+| --------- | -------------- | --------------------------- |
 | `'pt-BR'` | Português (BR) | `'pt-BR'` in `localStorage` |
-| `'en'` | English | `'en'` |
-| `'es'` | Español | `'es'` |
+| `'en'`    | English        | `'en'`                      |
+| `'es'`    | Español        | `'es'`                      |
 
 ---
 
@@ -190,41 +188,41 @@ The project uses a single `translation` namespace. Each top-level key maps to a
 
 **Root files** (`locales/<lang>/<key>.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` |
+| 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/<lang>/pages/<key>.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` |
+| 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/<lang>/components/<key>.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` |
+| 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`                                                      |
 
 ---
 
@@ -237,11 +235,13 @@ Mock data fetch functions use `i18n.t()` (the instance, not the hook) so they re
 import i18n from '../../../i18n';
 
 export async function fetchFeatureCards(): Promise<FeatureCard[]> {
-  return [{
-    id: 'template-cli',
-    title: i18n.t('home.templateCliTitle'),       // ← translated at query time
-    description: i18n.t('home.templateCliDescription'),
-  }];
+  return [
+    {
+      id: 'template-cli',
+      title: i18n.t('home.templateCliTitle'), // ← translated at query time
+      description: i18n.t('home.templateCliDescription'),
+    },
+  ];
 }
 ```
 
@@ -264,6 +264,7 @@ export function useFeatureCards() {
 ```
 
 **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
@@ -278,9 +279,7 @@ When you need static fallback data while a query loads, use **factory functions*
 ```ts
 // ✅ Correct — evaluated at call time, always returns current language
 export function getMockRichSuggestions(): Suggestion[] {
-  return [
-    { id: 'rich-1', text: i18n.t('assistant.richSuggestions.viewPerformance') },
-  ];
+  return [{ id: 'rich-1', text: i18n.t('assistant.richSuggestions.viewPerformance') }];
 }
 
 // ❌ Wrong — i18n.t() runs once at module load, frozen in initial language
@@ -312,11 +311,13 @@ $ npx xertica-ui init my-app
 ```
 
 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.
@@ -341,6 +342,7 @@ Current languages: Português (BR), English
 ```
 
 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/<lang>/`.
 3. Removes the **folders** of unselected languages from your project (also removes any legacy flat `<lang>.json` files if upgrading from pre-2.2.0).
@@ -358,7 +360,7 @@ import { XerticaProvider } from 'xertica-ui';
 
 <XerticaProvider>
   {/* pt-BR, en, es are all available — selector shows all three */}
-</XerticaProvider>
+</XerticaProvider>;
 ```
 
 ### Monolingual — single language, no selector
@@ -390,7 +392,7 @@ import fr from './locales/fr.json';
   ]}
 >
   {/* French now appears in the selector; its strings are registered automatically */}
-</XerticaProvider>
+</XerticaProvider>;
 ```
 
 The provider calls `i18n.addResourceBundle()` on mount for any entry that carries `resources`.
@@ -414,10 +416,12 @@ registerLanguageResource('fr', fr);
 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
-<XerticaProvider availableLanguages={[
-  { code: 'pt-BR', label: 'Português' },
-  { code: 'en',    label: 'English' },
-]}>
+<XerticaProvider
+  availableLanguages={[
+    { code: 'pt-BR', label: 'Português' },
+    { code: 'en', label: 'English' },
+  ]}
+>
   {/* Only Portuguese and English appear — Spanish is hidden */}
 </XerticaProvider>
 ```
@@ -451,10 +455,10 @@ interface LanguageDefinition {
 
 ```ts
 const {
-  language,             // current locale code
-  setLanguage,          // change locale + persist + invalidate React Query
-  availableLanguages,   // LanguageDefinition[] currently configured
-  isMonolingual,        // true when availableLanguages.length === 1
+  language, // current locale code
+  setLanguage, // change locale + persist + invalidate React Query
+  availableLanguages, // LanguageDefinition[] currently configured
+  isMonolingual, // true when availableLanguages.length === 1
 } = useLanguage();
 ```