@mmstack/translate 21.1.11 → 21.1.13

package/README.md

@@ -164,7 +164,8 @@ export default createQuoteTranslation('sl-SI', {
   errors: {
     minLength: 'Citat mora imeti vsaj {min} znakov.', // Variables must match original
   },
-  stats: '{count, plural, =1 {# citat} =2 {# citata} few {# citati} other {# citatov}} na voljo',
+  stats:
+    '{count, plural, =1 {# citat} =2 {# citata} few {# citati} other {# citatov}} na voljo',
 });
 ```
 
@@ -223,7 +224,10 @@ export class QuoteTranslator extends Translator<QuoteLocale> {}
 @Directive({
   selector: '[translate]', // Input in Translate is named 'translate'
 })
-export class QuoteTranslate<TInput extends string> extends Translate<TInput, QuoteLocale> {}
+export class QuoteTranslate<TInput extends string> extends Translate<
+  TInput,
+  QuoteLocale
+> {}
 ```
 
 ### 3. Use Translations in Components
@@ -320,7 +324,8 @@ export const routes: Routes = [
     children: [
       {
         path: 'quotes',
-        loadChildren: () => import('./quote/quote.routes').then((m) => m.QUOTE_ROUTES),
+        loadChildren: () =>
+          import('./quote/quote.routes').then((m) => m.QUOTE_ROUTES),
       },
       // ... other routes
     ],
@@ -451,9 +456,12 @@ export const createAppNamespace = ns.createMergedNamespace;
 // common.t.ts
 import { registerNamespace } from '@mmstack/translate';
 
-const r = registerNamespace(() => import('./common.namespace').then((m) => m.default), {
-  'sl-SI': () => import('./common-sl.translation').then((m) => m.default),
-});
+const r = registerNamespace(
+  () => import('./common.namespace').then((m) => m.default),
+  {
+    'sl-SI': () => import('./common-sl.translation').then((m) => m.default),
+  },
+);
 
 export const injectCommonT = r.injectNamespaceT;
 export const resolveCommonTranslations = r.resolveNamespaceTranslation;
@@ -564,9 +572,13 @@ For cases where you need to load translations from a remote API (where keys aren
 import { registerRemoteNamespace } from '@mmstack/translate';
 
 // Returns an untyped t function: t('any.key')
-const { injectNamespaceT: injectRemoteT } = registerRemoteNamespace('remote', () => fetch('/api/en').then((r) => r.json()), {
-  'sl-SI': () => fetch('/api/sl').then((r) => r.json()),
-});
+const { injectNamespaceT: injectRemoteT } = registerRemoteNamespace(
+  'remote',
+  () => fetch('/api/en').then((r) => r.json()),
+  {
+    'sl-SI': () => fetch('/api/sl').then((r) => r.json()),
+  },
+);
 
 // usage
 const t = injectRemoteT();
@@ -580,15 +592,7 @@ const valueThatNeedsProps = t('remote.myOtherKey', {
 
 ## Formatters
 
-The library includes a set of reactive formatters that automatically adapt to the current locale. They are standalone functions that do not require dependency injection, making them easy to use anywhere.
-
-**Note:** For reactivity, wrap them in a `computed()` if the input signals change or if you want them to react to dynamic locale changes.
-
-**SSR note:** Formatters read the active locale from a process-level signal. This is safe for all client-side usage and for SSR on serverless platforms (Lambda, Vercel, Netlify Edge) or worker-thread pools, where each request runs in an isolated V8 context. If you run a traditional single-process Node.js SSR server and concurrently render pages for **different** locales, pass the locale explicitly via the `locale` option on each formatter to avoid a potential cross-request read:
-
-```typescript
-readonly displayDate = computed(() => formatDate(this.date, { locale: this.currentLocale() }));
-```
+The library includes a set of reactive formatters that wrap the standard `Intl.*` APIs and integrate with the dynamic locale signal.
 
 Available formatters:
 
@@ -600,24 +604,82 @@ Available formatters:
 - **`formatRelativeTime`**: Wraps `Intl.RelativeTimeFormat`
 - **`formatDisplayName`**: Wraps `Intl.DisplayNames`
 
-**Example:**
+Each formatter ships in two flavors:
+
+1. **Standalone function** (`formatDate`, `formatList`, …) — pass `locale` explicitly, either as a string or via the options object. Three overloads per formatter: `(value, locale)`, `(value, opt)` with a required `locale` field, and a deprecated unsafe form that omits the locale (kept for backwards compatibility, see SSR note below).
+2. **`injectFormat*()` companion** (`injectFormatDate`, `injectFormatList`, …) — call inside an injection context to get a function that auto-resolves locale from `injectDynamicLocale()` and respects any defaults registered via `provideFormat*Defaults`. **This is the recommended path for components and services.**
+
+You can grab them all at once via the `injectFormatters()` facade:
 
 ```typescript
 import { computed, signal } from '@angular/core';
-import { formatCurrency, formatDate } from '@mmstack/translate';
+import { injectFormatters } from '@mmstack/translate';
 
 export class MyComponent {
+  private readonly fmt = injectFormatters();
+
   readonly price = signal(1234.56);
   readonly date = new Date();
 
-  // Reacts to price changes OR locale changes
-  readonly displayPrice = computed(() => formatCurrency(this.price(), 'EUR'));
-
-  // Reacts to locale changes
-  readonly displayDate = computed(() => formatDate(this.date));
+  // Reacts to price changes AND locale changes — no explicit locale needed
+  readonly displayPrice = computed(() => this.fmt.currency(this.price(), 'EUR'));
+  readonly displayDate = computed(() => this.fmt.date(this.date));
 }
 ```
 
+If you'd rather call the standalone forms (e.g. outside an injection context), pass the locale explicitly:
+
+```typescript
+import { computed } from '@angular/core';
+import { formatCurrency, formatDate, injectDynamicLocale } from '@mmstack/translate';
+
+const locale = injectDynamicLocale();
+
+readonly displayPrice = computed(() => formatCurrency(this.price(), 'EUR', { locale: locale() }));
+readonly displayDate = computed(() => formatDate(this.date, locale()));
+```
+
+### Provider defaults
+
+Each formatter has a paired `provideFormat*Defaults` provider, and they can be registered together via `provideFormatDefaults`:
+
+```typescript
+import { provideFormatDefaults } from '@mmstack/translate';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideFormatDefaults({
+      date: { format: 'mediumDate' },
+      number: { useGrouping: true, maxFractionDigits: 2 },
+      currency: { display: 'code' },
+      relativeTime: { numeric: 'auto' },
+      list: { type: 'disjunction' },
+      percent: { maxFractionDigits: 1 },
+      displayName: { style: 'short' },
+    }),
+  ],
+});
+```
+
+The injected formatter functions (`injectFormat*()`) automatically merge these defaults with the dynamic locale.
+
+### SSR note
+
+The deprecated unsafe overload (omitting `locale`) reads from a **process-level global signal**, which can cross-contaminate concurrent requests on a single-process Node.js SSR server rendering pages for different locales. The new overloads with required `locale` and the `injectFormat*()` companions are SSR-safe.
+
+For SSR-bound code, prefer either:
+
+```typescript
+// 1. Recommended — let the injected formatter handle locale
+private readonly formatDate = injectFormatDate();
+readonly displayDate = computed(() => this.formatDate(this.date));
+
+// 2. Or pass locale explicitly to the standalone function
+readonly displayDate = computed(() => formatDate(this.date, this.currentLocale()));
+```
+
+The unsafe overload is kept for backwards compatibility and will be removed in a future release.
+
 ## Testing
 
 When testing components that use `@mmstack/translate` (via `injectNamespaceT`, `Translate` directive, or `Translator` pipe), you don't need to configure actual translated namespaces or deal with Intl loading. Instead, use the provided `provideMockTranslations()` utility.
@@ -643,7 +705,9 @@ describe('MyComponent', () => {
     fixture.detectChanges();
 
     // By default, it echoes back the flattened object key using dot notation
-    expect(fixture.nativeElement.textContent).toContain('myNamespace.greeting.title');
+    expect(fixture.nativeElement.textContent).toContain(
+      'myNamespace.greeting.title',
+    );
   });
 
   it('allows providing explicit mock overrides', () => {
@@ -704,6 +768,64 @@ If you're migrating from a runtime-only solution:
 4. Convert your translation JSON files to TypeScript using `createNamespace`
 5. Update component/template usage to use the type-safe APIs
 
+## Escape Hatches
+
+Sometimes we all hit the limit of an api & need imperitive escape hatches for those edge cases. These are the ones mmstack/translate currently provides:
+
+**`withParams()`**
+
+Type-level parameter inference is one level deep — variables inside `plural` / `select` / `selectordinal` arms aren't picked up (e.g. the `{name}` inside `{count, plural, one {Hi {name}} ...}`). For those cases, wrap the message with `withParams<P>(...)` to declare the missing params explicitly:
+
+```typescript
+import { createNamespace, withParams } from '@mmstack/translate';
+
+const ns = createNamespace('quote', {
+  // auto-extracts `count`; `name` is declared because it lives inside the arms
+  stats: withParams<{ name: string }>(
+    '{count, plural, one {1 quote from {name}} other {# quotes from {name}}}',
+  ),
+});
+
+// t inferred as: ('quote.stats', { count: number; name: string }) => string
+t('quote.stats', { count: 3, name: 'Alice' });
+```
+
+Declared params are merged with auto-extracted ones; on key conflict, declared wins. Non-default locales for a wrapped key don't need to repeat the helper — they accept any string:
+
+```typescript
+createQuoteTranslation('sl-SI', {
+  stats: '{count, plural, =1 {1 citat od {name}} other {# citatov od {name}}}',
+});
+```
+
+Trade-off: wrapping a key opts out of template-literal shape strictness for that key in non-default locales (the auto-validation that requires placeholders to appear in the right positions). The library still enforces top-level placeholders for non-wrapped keys.
+
+**`injectAddTranslations()`**
+Allows adding flat, per-locale translations to any namespace at runtime.
+
+```typescript
+import { injectAddTranslations } from '@mmstack/translate';
+
+const addTranslations = injectAddTranslations();
+addTranslations('dynamicNs', {
+  'en-US': { greeting: 'Hello {name}!' },
+  'sl-SI': { greeting: 'Zdravo {name}!' },
+});
+```
+
+**`injectUnsafeT()`**
+Returns a fully untyped translation function `t('anyNamespace.key')`. Ideal for reading dynamically added keys or cross-namespace lookups where the typed API would be impractical.
+
+```typescript
+import { injectUnsafeT } from '@mmstack/translate';
+
+const t = injectUnsafeT();
+const greeting = t('dynamicNs.greeting', { name: 'Alice' });
+const signalGreeting = t.asSignal('dynamicNs.greeting', () => ({
+  name: 'Alice',
+}));
+```
+
 ## Contributing
 
 Contributions, issues, and feature requests are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.