@nxgt/material-vue 0.21.0 → 0.22.0

package/docs/guides/i18n.md

@@ -0,0 +1,491 @@
+# i18n
+
+This page covers how to show the components in French or English, switch
+language at runtime, type your own strings, and translate Zod messages. The
+package owns the i18n **mechanism**. Your app owns the resource **content**.
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { LanguageSwitcher } from '@nxgt/material-vue/components';
+import { I18nProvider } from '@nxgt/material-vue/i18n';
+</script>
+
+<template>
+  <I18nProvider default-language="en">
+    <LanguageSwitcher />
+    <RouterView />
+  </I18nProvider>
+</template>
+```
+
+That is enough for the package's own strings (empty states, dialogs, table
+pagination, field hints…) to follow the language. `LanguageSwitcher` lists the
+provider's `supportedLanguages` (or its own `languages` prop) and changes the
+language for the whole tree, with no reload. Outside a provider it renders
+disabled.
+
+`I18nProvider` is a renderless component: it provides the language and
+renders its default slot. If you would rather not add a wrapper, call
+`provideI18n()` in the root component's `setup` — it takes the same options:
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { provideI18n } from '@nxgt/material-vue/i18n';
+
+provideI18n({ defaultLanguage: 'en' });
+</script>
+
+<template>
+  <RouterView />
+</template>
+```
+
+The Nuxt module does not auto-register `I18nProvider` (it lives in `/i18n`,
+not `/components`); import it.
+
+## Without a provider
+
+Every component keeps working with no `I18nProvider` mounted: it renders its
+built-in English copy. Adopting i18n later is additive.
+
+That copy is formatted like a translation, so counts and positions are filled
+in: a stepper reads `Step 01`, a Kanban WIP badge `3/5`, a `JsonViewer` node
+`3 items`, never `Step {step}`, `{count}/{max}` or `{count} items`. This holds
+on a server too. The same happens under a provider when the language's bundle
+lacks a key.
+
+Your own components can do the same with `useMaterialTranslation()`, whose
+`t(key, fallback, values)` formats `fallback` with `values` when there is no
+provider or no string for `key`:
+
+```vue
+<script setup lang="ts">
+import { useMaterialTranslation } from '@nxgt/material-vue/i18n';
+
+const { t } = useMaterialTranslation();
+</script>
+
+<template>
+  <!-- 'Step 2', 'Étape 2' in French -->
+  <span>{{ t('material.stepper.step', 'Step {step}', { step: 2 }) }}</span>
+</template>
+```
+
+It only knows the package's `material.*` keys. It also returns `language`
+(`undefined` without a provider) and `hasProvider`.
+
+### Outside a component
+
+Where there is no component to call a composable in (a PDF's page-number
+callback, a server route, a worker), `translateMaterial()` takes the language as
+a value. No plugin, no provider, no composable:
+
+```ts
+import { translateMaterial } from '@nxgt/material-vue/i18n';
+
+translateMaterial('fr', 'material.print.page-of', 'Page {page} of {pages}', { page: 2, pages: 5 });
+// 'Page 2 sur 5'
+translateMaterial('fr-CA', 'material.print.page-of', 'Page {page} of {pages}', { page: 2, pages: 5 });
+// 'Page 2 sur 5': a regional tag reads its language
+translateMaterial('de', 'material.print.page-of', 'Seite {page} von {pages}', { page: 2, pages: 5 });
+// 'Seite 2 von 5': a language the bundle lacks formats the fallback
+translateMaterial(undefined, 'material.print.page', 'Page {page}', { page: 3 });
+// 'Page 3': no language formats the fallback too
+```
+
+```ts
+function translateMaterial(
+  language: string | null | undefined,
+  key: MaterialLocaleKey,
+  fallback: string,
+  values?: TranslationContext,
+): string;
+```
+
+- `language` is any BCP 47 tag. The exact tag is tried first, then its
+  language (`'fr-CA'` → `fr`).
+- With no language, a language the bundle does not have, or a key it does not
+  have, `fallback` is formatted with `values` under that language's `Intl`
+  rules (English with no language). It never returns the key and never throws.
+- It reads the package's own bundle, so your overrides of `material.*` in
+  `mergeResources` do not apply, as for the components.
+- `useMaterialTranslation().t` goes through it with the provider's language:
+  the two give the same string for the same language.
+
+The `material.print` keys are there for printed documents: page numbers
+(`material.print.page-of`, "Page {page} of {pages}" / "Page {page} sur
+{pages}", and `material.print.page`, "Page {page}") and tables
+(`material.print.table.total`, "Total", and `material.print.table.empty`,
+"No rows" / "Aucune ligne").
+
+## Wiring your own strings
+
+Keep your strings in your own namespaces, merge them with the package's
+bundle, and build a typed translator and composable **once**:
+
+```ts
+// i18n/resources.ts
+export const resources = {
+  en: {
+    app: {
+      greeting: 'Hello {name}',
+      cart: '{count, plural, =0 {Your cart is empty} one {# item} other {# items}}',
+    },
+  },
+  fr: {
+    app: {
+      greeting: 'Bonjour {name}',
+      cart: '{count, plural, =0 {Votre panier est vide} one {# article} other {# articles}}',
+    },
+  },
+};
+```
+
+```ts
+// i18n/index.ts
+import {
+  createTranslator,
+  createTypedTranslation,
+  type FlatObject,
+  mergeResources,
+  resources as materialResources,
+} from '@nxgt/material-vue/i18n';
+import { resources as appResources } from './resources';
+
+export const resources = mergeResources(materialResources, appResources);
+export type LocaleKey = keyof FlatObject<typeof resources.en, string>;
+export const translate = createTranslator<LocaleKey>(resources);
+export const useTranslation = createTypedTranslation<LocaleKey>(translate);
+```
+
+```vue
+<!-- CartSummary.vue, anywhere under <I18nProvider> -->
+<script setup lang="ts">
+import { useTranslation } from './i18n';
+
+defineProps<{ name: string; count: number }>();
+const { t, i18n } = useTranslation();
+</script>
+
+<template>
+  <p>
+    {{ t('app.greeting', { name }) }}: {{ t('app.cart', { count }) }}
+    <button type="button" @click="i18n.changeLanguage('fr')">FR</button>
+  </p>
+</template>
+```
+
+- `LocaleKey` is the union of every leaf path (`'app.greeting'`,
+  `'material.command.title'`, …), so a typo in a key is a type error.
+- Messages are [ICU MessageFormat](https://formatjs.github.io/docs/core-concepts/icu-syntax/)
+  (`intl-messageformat`): `{name}`, plurals, selects.
+- **A missing key is returned as-is** (`t('app.nope')` → `'app.nope'`). A
+  message that is not valid ICU is logged with `console.error` and returned
+  unformatted. Neither throws.
+- `useTranslation()` from `createTypedTranslation` must be called in the
+  `setup` of a component under `I18nProvider`; it throws
+  `useI18nContext must be used within an I18nProvider` otherwise.
+- **`t` and `i18n.language` follow `changeLanguage`.** They read the
+  provider's language on every call, so a template that calls `t(…)` re-renders
+  in the new language in place. Keep the returned `i18n` object: destructuring
+  `language` out of it (or out of `useI18nContext()`) copies the current value.
+
+```ts
+function createTranslator<K extends string>(
+  bundle?: Record<string, any>,
+  localeProvider?: (() => Language) | Language, // default: getLanguage(), reads localStorage
+): (key: K, context?: TranslationContext, language?: (() => Language) | Language) => string;
+
+function createTypedTranslation<K extends string>(translate: Translate<K>): () => {
+  t: (key: K, context?: TranslationContext) => string;
+  i18n: { language: Language; changeLanguage: (value: Language) => void };
+};
+```
+
+`translate` from your `i18n/index.ts` also works outside components: router
+guards, stores, toasts, table column definitions. Without a third argument it
+reads the language from `localStorage` under the key `language` (`'en'` on a
+server), so pass one where you know it:
+`translate('app.greeting', { name }, 'fr')`.
+
+## `I18nProvider`
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `default-language` | `Language` | `'en'` | Used when nothing valid is stored |
+| `initial-language` | `Language` | — | Used as-is for the first render when supported, and `localStorage` is not read. Set it in SSR. See [below](#server-rendering) |
+| `storage-key` | `string` | `'language'` | `localStorage` key the choice is read from and written to |
+| `supported-languages` | `Language[]` | `['en', 'fr']` | What `changeLanguage` accepts and `LanguageSwitcher` lists |
+| `on-language-change` | `(language) => void` | — | Called after a successful change: save it to a cookie, a profile, analytics |
+
+`changeLanguage` with an unsupported value logs
+`[@nxgt/material-vue] Unsupported language: "de".` with `console.warn` and
+does nothing. If storage is unavailable (private mode, quota), the language
+still changes for the session.
+
+Reading the state, in `setup`:
+
+```ts
+import { useI18nContext, useOptionalI18nContext } from '@nxgt/material-vue/i18n';
+
+const i18n = useI18nContext(); // throws outside the provider
+i18n.language; // reactive: read it in a computed or the template, do not destructure it
+i18n.changeLanguage('fr');
+i18n.supportedLanguages;
+
+const maybe = useOptionalI18nContext(); // null outside the provider
+```
+
+The context is a `reactive` object: `i18n.language` is tracked where it is
+read, and a destructured `const { language } = useI18nContext()` is a
+snapshot.
+
+`Language` is `'en' | 'fr'`: the languages the package ships strings for. A
+third language is not in the type today, so adding one to
+`supported-languages` takes a cast. The runtime accepts it: your translator
+uses your strings for it, and the components fall back to their English copy.
+
+```vue
+<script setup lang="ts">
+import { I18nProvider, type Language } from '@nxgt/material-vue/i18n';
+
+const languages = ['en', 'fr', 'de'] as Language[];
+</script>
+
+<template>
+  <I18nProvider :supported-languages="languages">
+    <RouterView />
+  </I18nProvider>
+</template>
+```
+
+## The `material` namespace
+
+The package's own strings live under one top-level namespace per language,
+`material` (`material.command.title`, `material['empty-state'].*`, …).
+`mergeResources` deep-merges per language (`lodash.merge`): keys unique to
+either side are kept, and where both define the same leaf, **your value
+wins**.
+
+The copy components render on their own comes from this namespace: empty
+states, dialogs, pickers, the rich-text editor's toolbar, menus, node dialogs,
+slash menu, font names and table-caption alignment
+(`material['rich-text-editor'].*`), the carousel, the camera, the
+autocomplete, the QR code and barcode accessible names, the calendar's
+previous and next buttons, `DateRangeField`'s included (`material.calendar.*`), the data table's selection
+checkboxes, the filter's presets and `Min`/`Max` fields, the `variant="4"` spinner's label,
+`ScrollToTop`, the network upload field's `Retry`/`Remove`, the map's
+`You are here` and zoom buttons, and the close button of dialogs, sheets and
+`DialogFooter`. The other icon-only buttons are named from it too: the
+`Sidebar` toggle (`material.sidebar.toggle`), the data table's row expander
+(`material.table.labels.toggle-row`), a `Chip`'s remove button, which the
+`Autocomplete` chips use ("Remove {label}", `material.chip.dismiss-label`),
+the `LocationPreview` trigger (`material.map.preview` / `preview-named`),
+`DurationField`'s inputs, "Hours" and "Minutes"
+(`material['duration-field']['hours-label']` / `minutes-label`), and
+the delete button of the deprecated `ContactItem` / `OpeningHoursItem`
+(`material.contacts.buttons.remove`,
+`material['opening-hours'].buttons.remove`). The keys and the French are the
+same in `@nxgt/material`, so one set of overrides fits both. Text you pass yourself always wins over the
+translation: a `label`, an `aria-label` on `Spinner`, `ScrollToTop`,
+`CalendarPrevButton` or `CalendarNextButton`, and `LocationMarker`'s
+`#tooltip` slot.
+
+Smaller labels follow the language the same way: the pagination buttons'
+names and text, which reka-ui left in English (`material.pagination.first`,
+`previous`, `next`, `last`, `page`, and `more` for the ellipsis), and the
+`aria-label` of `Pagination` and `Breadcrumb` and the breadcrumb ellipsis's
+"More" (`material.pagination.label`, `material.breadcrumb.*`), and
+`DocHeader`'s breadcrumb (`material.doc.breadcrumb`); `CommandDialog`'s
+default title and description (`material.command.*`); the carousel's
+`aria-roledescription` (`material.carousel.roledescription` / `slide`); the
+filter's empty state and `+N more` chip (`material.filter.empty` / `more`) and
+the Yes/No, From, Until and Up to of its chips (`material.filter.value.*`;
+`formatFilterValue` takes those words as an optional third argument);
+`MessageCard`'s "Unread" (`material.cards.unread`); the network upload
+field's "Replace {name}", "Upload failed" and its type, size and count errors
+(`material.upload.replace-named`, `failed`, `invalid-type`, `too-large`,
+`max-files`; `getValidationMessage` and `getUploadErrorMessage` take `t` as
+an optional last argument, and an error keeps the language it was raised in)
+and the drop zone's "Max {size}" and "Up to {count} files"
+(`material.upload.dropzone.max-size` / `max-files`);
+the attribute options' "Add option" (`material.attributes.buttons.add-option`);
+the editor's placeholder, which
+follows a language change without rebuilding the editor, and its emoji
+buttons (`material['rich-text-editor'].placeholder` / `insert-emoji`);
+`CircularProgress`'s "Progress: {value}%"
+(`material['circular-progress'].label`); `StxPlayer`'s "Media player" for a
+track without a title (`material['stx-player'].label`); `PaneLayoutPane`'s
+sheet title on a phone (`material['pane-layout']['sheet-title']`);
+`JsonViewer`'s "Empty JSON" (`material['json-viewer'].empty`); and
+`TimePicker`'s AM/PM (`material['time-picker'].am` / `pm`, "a.m." / "p.m." in
+French). Your `placeholder`, `sheetTitle`, `title`, `description` and
+`aria-label` still win.
+
+To format filter values yourself in the provider's language, pass
+`formatFilterValue` the same words `FilterChips` uses (`FilterValueWords`; the
+English is `FILTER_VALUE_WORDS`). The upload helpers take the translator
+itself (`UploadMessageTranslate`, which `useMaterialTranslation().t` fits):
+
+```ts
+import { computed } from 'vue';
+import {
+  type FilterValueWords,
+  formatFilterValue,
+  getValidationMessage,
+} from '@nxgt/material-vue/components';
+import { useMaterialTranslation } from '@nxgt/material-vue/i18n';
+
+// in a component's setup; `computed` keeps Yes/No following a language change
+const { t } = useMaterialTranslation();
+const words = computed<FilterValueWords>(() => ({
+  yes: t('material.filter.value.yes', 'Yes'),
+  no: t('material.filter.value.no', 'No'),
+  from: (value) => t('material.filter.value.from', 'From {value}', { value }),
+  until: (value) => t('material.filter.value.until', 'Until {value}', { value }),
+  upTo: (value) => t('material.filter.value.up-to', 'Up to {value}', { value }),
+}));
+// field: one of your FilterField definitions, value: its current value
+formatFilterValue(field, value, words.value); // "À partir de 5" in French
+getValidationMessage('max-files', { maxFiles: 3 }, t); // "Maximum de 3 fichiers atteint"
+```
+
+The editor's slash menu matches what you type against the translated title
+and description and against the English ones, ignoring accents: in French,
+`/titre`, `/heading` and `/separateur` all work.
+
+Some strings are still English in every language, among them the filter's
+validation messages, the camera's error messages, the editor's callout type
+names and default block content, and the names of the emoji picker's category
+tabs. File sizes (`2.0 KB`) and the filter chips' dates are not formatted for
+the provider's language.
+
+That override is visible only through **your** translator. The components
+translate through the package's own bundle, so defining
+`material.command.title` in your resources changes what
+`t('material.command.title')` returns in your code, but not the title
+`CommandDialog` renders.
+
+Each time `mergeResources` runs outside production, overlapping leaves are
+reported with `console.warn`, one line per language:
+
+```text
+[@nxgt/material-vue] i18n resource override for language "en": material.command.title. App resources take precedence over the base bundle at these keys.
+```
+
+If you see that warning and did not mean it, move your key out of `material`.
+
+## Zod messages
+
+```ts
+// main.ts
+import { z } from 'zod';
+import { zodLocaleError } from '@nxgt/material-vue/lib';
+
+z.config({ customError: zodLocaleError() });
+```
+
+The error map formats Zod v4 issues from `material.zod.*` (required, too
+short, too big, invalid email…). It is independent of the provider: by default
+it reads `localStorage.language` itself (`'fr'` → French, anything else →
+English) and formats from the package's own bundle. On a server, or when
+storage cannot be read, it writes English.
+
+Three options line it up with the rest of your i18n:
+
+```ts
+// main.ts
+import { z } from 'zod';
+import { zodLocaleError } from '@nxgt/material-vue/lib';
+import { translate } from './i18n'; // createTranslator(mergeResources(...)), above
+
+z.config({
+  customError: zodLocaleError({
+    storageKey: 'lang', // the storage-key you gave I18nProvider
+    translate, // your overrides of material.zod.* apply
+  }),
+});
+```
+
+- `storageKey`: where the language is read from. Default `'language'`.
+- `language`: a language, or a function returning one, used instead of
+  storage. Use it on a server, where you know the request's language.
+- `translate`: the translator to format with. Default: the package's own.
+
+Examples and per-field messages are in [forms](forms.md#validation-messages).
+
+## Server rendering
+
+On the server there is no `localStorage`, so without help the server renders
+`default-language` and a French visitor's browser switches after hydration: a
+mismatch. Resolve the language from the request and pass it as
+`initial-language`, then persist changes where the server can read them. In
+Nuxt:
+
+```vue
+<!-- app.vue -->
+<script setup lang="ts">
+import { I18nProvider, type Language } from '@nxgt/material-vue/i18n';
+
+const cookie = useCookie<Language | undefined>('lang', {
+  maxAge: 31536000,
+  sameSite: 'lax',
+});
+const acceptLanguage = useRequestHeaders(['accept-language'])['accept-language'];
+
+const language: Language =
+  cookie.value === 'en' || cookie.value === 'fr'
+    ? cookie.value
+    : acceptLanguage?.toLowerCase().startsWith('fr')
+      ? 'fr'
+      : 'en';
+
+function persist(next: Language) {
+  cookie.value = next;
+}
+</script>
+
+<template>
+  <I18nProvider :initial-language="language" :on-language-change="persist">
+    <NuxtPage />
+  </I18nProvider>
+</template>
+```
+
+`useCookie` and `useRequestHeaders` are Nuxt's; in a hand-written Vite SSR
+server, read the same two values from the request, pass the result to the root
+component, and serialise it into the page so server and client start from the
+same value. More on server rendering in [SSR](ssr.md).
+
+## Dates and numbers
+
+`useLocalizedDate()`, `useFormatters()` and `useNumberFormatter()` from
+`@nxgt/material-vue/composables` bind date-fns and `Intl` to the provider's
+language (English without one):
+
+```vue
+<script setup lang="ts">
+import { useFormatters, useLocalizedDate, useNumberFormatter } from '@nxgt/material-vue/composables';
+
+const date = useLocalizedDate();
+const { formatAmount } = useFormatters();
+const { formatNumber } = useNumberFormatter();
+</script>
+
+<template>
+  <p>{{ date.format('2026-03-14T09:00:00Z', 'PPP') }} — {{ formatAmount(1234.5, 'EUR') }}</p>
+  <p>{{ formatNumber(0.25, { style: 'percent' }) }}</p>
+</template>
+```
+
+For money and dates shown to a user, `useFormatters()` (`formatAmount`,
+`formatDate`) prints what the PDF builders print, with the decimals `CurrencyField` shows;
+`useNumberFormatter()` is for the other `Intl.NumberFormat` styles
+(percentages, units). See [helpers](helpers.md#nxgtmaterial-vuecomposables).
+
+## Reference
+
+Everything `@nxgt/material-vue/i18n` exports is listed in
+[helpers](helpers.md#nxgtmaterial-vuei18n).