@zerotal/i18n 1.7.0 → 1.7.3

package/api-surface.md

@@ -64,6 +64,8 @@ class Translator = {
 
 const Lang = Translator
 
+function __ = (key: string, replacements?: Replacements, locale?: string) => string
+
 function I18nConfig = (options?: Partial<I18nConfigShape>) => I18nConfigShape
 
 function loadCatalogs = (dir: string) => Promise<Catalogs>
@@ -72,8 +74,6 @@ function parseAcceptLanguage = (header: string | null) => string[]
 
 function resolveLocale = (request: Request, config: I18nConfigShape) => string
 
-function t = (key: string, replacements?: Replacements, locale?: string) => string
-
 interface I18nConfigShape = {
   catalogs?: Catalogs
   cookieKey: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/i18n",
-  "version": "1.7.0",
+  "version": "1.7.3",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -33,7 +33,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.7.0"
+    "@zerotal/core": "1.7.3"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/LocaleMiddleware.ts

@@ -5,9 +5,9 @@ import type { Translator } from "./Translator.ts";
 import type { I18nConfigShape } from "./config.ts";
 
 /**
- * Resolves the request locale, exposes `ctx.locale` + `ctx.t()`, and runs the
+ * Resolves the request locale, exposes `ctx.locale` + `ctx.__()`, and runs the
  * rest of the pipeline inside `I18nContext.run()` so the `Lang` facade and the
- * global `t()` helper see the right locale. Configured by I18nProvider via
+ * global `__()` helper see the right locale. Configured by I18nProvider via
  * `LocaleMiddleware.configure()` and registered with `app.useOnce()`.
  */
 export class LocaleMiddleware implements Pipe<HttpContext> {
@@ -26,7 +26,7 @@ export class LocaleMiddleware implements Pipe<HttpContext> {
 
     const locale = resolveLocale(http.request, config);
     http.locale = locale;
-    http.t = (key, replacements, loc) => translator.translate(key, replacements, loc ?? locale);
+    http.__ = (key, replacements, loc) => translator.translate(key, replacements, loc ?? locale);
 
     return I18nContext.run(locale, () => next());
   }

package/src/Translator.ts

@@ -46,12 +46,21 @@ export class Translator {
   }
 
   /**
-   * Translate `key`. Missing keys return the key itself (so the UI degrades
-   * visibly rather than throwing).
+   * Translate `key`.
+   *
+   * An untranslated key falls through to *itself* — and then goes on to be
+   * pluralized and interpolated exactly like a catalog hit would be. That last
+   * part is what lets the source language skip having a catalog: write
+   * `translate('{count} comments', { count: 3 })` and English needs no `en.json`
+   * to answer with "3 comments", because the key already is the answer.
+   *
+   * The fallback is therefore never a broken-looking screen. A key nobody has
+   * translated renders as the English the developer typed, in a locale that has
+   * no entry for it, on the day the string is written.
    *
    * @example
-   * t.translate('welcome.greeting', { name: 'Alice' }, 'fr');
-   * t.translate('apples', { count: 2 }); // pipe-pluralized
+   * t.translate('Hello, {name}!', { name: 'Alice' }, 'fr');
+   * t.translate('{count} apple|{count} apples', { count: 2 }); // pipe-pluralized
    */
   translate(key: string, replacements: Replacements = {}, locale?: string): string {
     const loc = this._resolve(locale);
@@ -59,14 +68,23 @@ export class Translator {
     if (msg === undefined && loc !== this.fallbackLocale) {
       msg = this._lookup(key, this.fallbackLocale);
     }
-    if (msg === undefined) return key;
+    // The key is the source string, so it is a usable message on its own.
+    if (msg === undefined) msg = key;
     if (typeof replacements.count === "number") {
       msg = this._pluralize(msg, replacements.count);
     }
     return this._interpolate(msg, replacements);
   }
 
-  /** Look up a key as a flat dotted key first, then as a nested path. */
+  /**
+   * Look up a key flat first, then as a nested path.
+   *
+   * Flat has to come first, because an English key is a sentence: "Signed out."
+   * and "It costs $5. Really." both contain dots that are punctuation, not
+   * structure. Splitting those on `.` would send the lookup hunting for a
+   * `Signed out` object that no catalog has. Nested traversal stays as the
+   * second attempt so grouped catalogs keep resolving.
+   */
   private _lookup(key: string, locale: string): string | undefined {
     const cat = this.catalogs[locale];
     if (!cat) return undefined;

package/src/augment.ts

@@ -9,14 +9,29 @@ declare module "@zerotal/core" {
 
   interface HttpContext {
     /**
-     * Translate a key using this request's resolved locale.
+     * Translate an English source string using this request's resolved locale.
      *
      * @example
-     * ctx.t('welcome.greeting', { name: 'Alice' });
-     * ctx.t('welcome.greeting', { name: 'Alice' }, 'fr'); // explicit locale
+     * ctx.__('Hello, {name}!', { name: 'Alice' });
+     * ctx.__('Hello, {name}!', { name: 'Alice' }, 'fr'); // explicit locale
      */
-    t(key: string, replacements?: Replacements, locale?: string): string;
+    __(key: string, replacements?: Replacements, locale?: string): string;
   }
 }
 
+/**
+ * `__()` without an import.
+ *
+ * `I18nProvider` puts the helper on `globalThis` when it boots, and this is the
+ * declaration that lets a route or a view call `__("Email")` with no import
+ * line. The signature is the named export's, so nothing about a call site
+ * changes except what is missing from the top of the file.
+ *
+ * `var` rather than `const`, because only `var` in a `declare global` block
+ * creates a matching property on `globalThis` for the assignment to satisfy.
+ */
+declare global {
+  var __: (key: string, replacements?: Replacements, locale?: string) => string;
+}
+
 export {};

package/src/facades/Lang.ts

@@ -12,11 +12,19 @@ import type { Replacements } from "../types.ts";
 export const Lang = createFacade<"i18n">("i18n");
 
 /**
- * Convenience global translation helper — handy as a view global.
+ * The global translation helper.
+ *
+ * The argument is the English sentence, not a symbolic name: `__('Email')`,
+ * never `__('auth.email')`. English is the source language, so the source text
+ * doubles as the key — which means the default locale needs no catalog at all,
+ * and a string that has never been translated still renders as the words the
+ * developer wrote.
  *
  * @example
- * t('messages.unread', { count: 5 });
+ * __('Email');
+ * __('{count} unread', { count: 5 });
+ * __('Signed out.', {}, 'zu'); // explicit locale, for queue jobs
  */
-export function t(key: string, replacements?: Replacements, locale?: string): string {
+export function __(key: string, replacements?: Replacements, locale?: string): string {
   return Lang.translate(key, replacements, locale);
 }

package/src/index.ts

@@ -12,7 +12,7 @@ export { I18nProvider } from "./provider/I18nProvider.ts";
 export { LocaleMiddleware } from "./LocaleMiddleware.ts";
 
 // Facade + helper
-export { Lang, t } from "./facades/Lang.ts";
+export { Lang, __ } from "./facades/Lang.ts";
 
 // Config
 export { I18nConfig } from "./config.ts";

package/src/provider/I18nProvider.ts

@@ -5,6 +5,7 @@ import { loadCatalogs } from "../loadCatalogs.ts";
 import { LocaleMiddleware } from "../LocaleMiddleware.ts";
 import { I18nConfig } from "../config.ts";
 import type { I18nConfigShape } from "../config.ts";
+import { __ } from "../facades/Lang.ts";
 import "../augment.ts";
 
 /**
@@ -50,5 +51,15 @@ export class I18nProvider extends ServiceProvider {
     const config = await this._resolveConfig();
     LocaleMiddleware.configure(translator, config);
     this.app.useOnce(LocaleMiddleware);
+
+    // `__()` without an import, for every route, view, job and notification in
+    // the app. Installed here rather than at module load because it is only
+    // honest once there is a translator behind it: a global that resolves
+    // against an unbound container would answer every string with itself, which
+    // reads as "not translated yet" rather than as "i18n is not installed".
+    //
+    // The declaration that makes it type-check lives in `augment.ts`, beside the
+    // `HttpContext` one, since both are the same kind of ambient promise.
+    (globalThis as { __?: typeof __ }).__ = __;
   }
 }