@nxgt/i18n 1.0.1 → 1.0.3

package/README.md

@@ -1,39 +1,72 @@
 # @nxgt/i18n
 
-Backend-side i18n primitives shared by the Hono/GraphQL services: a tiny ICU
-translator (`createTranslator`, `translate`, `getLanguage`), the language
-constants (`LANGUAGE_KEY`, `FALLBACK_LANGUAGE`, `SUPPORTED_LANGUAGES`), the
-`LocaleKey`/`FlatObject`/`Path` types, and the base resource bundle
-(`common`, `errors`, `validation`, `zod`) that every service merges into its own.
+Message catalogues and ICU formatting (`intl-messageformat`) for every service,
+plus the `LocaleKey` type that `@nxgt/shared-exceptions` uses to type the
+message of a thrown error.
 
-## Scope: backend only
+An error message is a **key**, not a sentence: `CustomException` carries
+`'users.errors.not-found'` and the boundary that renders it decides the
+language. That is why `LocaleKey` lives this low in the layering.
 
-The UI apps (`apps/oauth/oauth`, `apps/oauth/oauth-admin`,
-`apps/storex/storex-ui`) do **not** use this package. They share their i18n
-mechanism through `@nxgt/material/i18n`, which adds the React side this package
-deliberately has none of: an `I18nProvider` holding the language in one context
-so a `changeLanguage()` re-renders every consumer, and `createTypedTranslation`
-to build each app's typed `useTranslation()`. Do not add a frontend consumer
-here — extend `@nxgt/material/i18n` instead.
+## Install
 
-## Consumers
+```bash
+bun add @nxgt/i18n
+```
 
-- `apps/gateway`
-- `apps/oauth/oauth-api`, `apps/storex/storex-api`
-- `apps/services/core`, `apps/services/locations`, `apps/services/notifications`
-- `packages/shared-exceptions`, `packages/shared-hono`, `packages/shared-mongo`,
-  `packages/shared-storage`
+Public on npmjs; no token needed to install. TypeScript is a peer, pinned to
+`^6.0.3` across every `@nxgt/*` package — the set is unsatisfiable if one of
+them widens it.
 
-A service builds its own translator over its own resources merged with this
-package's base bundle:
+## Usage
 
 ```ts
-import { createTranslator, resources as shared } from '@nxgt/i18n';
+import {
+	createTranslator,
+	getLanguage,
+	translate,
+	FALLBACK_LANGUAGE,
+	SUPPORTED_LANGUAGES,
+	LANGUAGE_KEY,
+} from '@nxgt/i18n';
 
-export const resources = {
-	en: { ...en, ...shared.en },
-	fr: { ...fr, ...shared.fr },
-};
+translate('errors.not-found');
 
-export const translate = createTranslator<LocaleKey>(resources);
+const t = createTranslator(myCatalogues, getLanguage);
+t('users.greeting', { name });
 ```
+
+`translate` is bound to this package's catalogues (`en` and `fr`, under
+`errors`, `common`, `validation`, `zod`). Pass your own catalogues to
+`createTranslator` when a service has messages this package does not. A missing
+key returns the key itself, not a throw.
+
+`LocaleKey` is `keyof` the flattened English catalogue — that is the type
+`CustomException.message` uses. `Language` is `'en' | 'fr'`. `resources`,
+`en` and `fr` are the catalogues themselves. Shared keys include
+`errors.not-found`, `errors.unauthenticated`, `errors.insufficient-permissions`
+and `errors.service-unavailable`.
+
+## Where the language comes from
+
+`getLanguage()` asks, most specific first:
+
+1. the Hono request context (`LANGUAGE_KEY`, `'language'`)
+2. `localStorage.language`, when that object exists
+3. `FALLBACK_LANGUAGE` (`'en'`)
+
+The two consuming monorepos had forked exactly this — one read the request, the
+other read `localStorage` — and neither could run where the other did. Asking
+both serves either without a caller changing anything. Pass a provider (a
+function or a `Language` literal) to `createTranslator` if you want one source
+and not the other.
+
+`SUPPORTED_LANGUAGES` is derived from the catalogue keys, not typed out.
+
+## Things that bite
+
+- **Messages are keys.** Rendering at the throw site (or translating in a
+  service) freezes the language of whoever threw, not of whoever reads.
+- **ICU formatting failures are swallowed** (`console.error`) and the
+  unformatted message is returned. A bad `{name}` in a catalogue is a log
+  line, not a 500.

package/dist/index.js

@@ -474,10 +474,10 @@ function getLanguage() {
   }
   return FALLBACK_LANGUAGE;
 }
-function createTranslator(resources2 = {}, localeProvider = getLanguage) {
+function createTranslator(resources = {}, localeProvider = getLanguage) {
   return (key, context = undefined, provideLanguage = localeProvider) => {
     const language = typeof provideLanguage === "function" ? provideLanguage() : provideLanguage;
-    let message = _.get(resources2[language], key) ?? key;
+    let message = _.get(resources[language], key) ?? key;
     try {
       message = new IntlMessageFormat(message, language).format(context);
     } catch (e) {
@@ -497,5 +497,5 @@ export {
   translate
 };
 
-//# debugId=629CBE18E4850F3E64756E2164756E21
+//# debugId=9824428B699DC6DF64756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -8,7 +8,7 @@
     "import { resources } from './resources';\nimport type { Language } from './types';\n\nexport const LANGUAGE_KEY = 'language';\n\nexport const SUPPORTED_LANGUAGES = Object.keys(resources) as Language[];\n\nexport const FALLBACK_LANGUAGE: Language = 'en';\n",
     "import { tryGetContext } from 'hono/context-storage';\nimport { IntlMessageFormat } from 'intl-messageformat';\nimport _ from 'lodash';\nimport { FALLBACK_LANGUAGE, LANGUAGE_KEY, SUPPORTED_LANGUAGES } from './consts';\nimport { resources } from './resources';\nimport type {\n\tLanguage,\n\tLanguageProvider,\n\tLocaleKey,\n\tTranslationContext,\n} from './types';\n\n/**\n * Where the language comes from when the caller does not say.\n *\n * The two repositories had forked exactly this: sellix-monorepo read\n * `localStorage`, nxgt-federation read the Hono request context, and neither\n * could run where the other did — federation's fell back to `'en'` outside a\n * request, sellix's knew nothing about one. Asking both, most specific first,\n * serves either without a caller changing anything.\n *\n * `createTranslator` still takes a provider, so a caller that wants one source\n * and not the other passes it.\n */\nexport function getLanguage(): Language {\n\tconst fromRequest: unknown = tryGetContext()?.get(LANGUAGE_KEY as never);\n\tif (\n\t\ttypeof fromRequest === 'string' &&\n\t\tSUPPORTED_LANGUAGES.includes(fromRequest as Language)\n\t) {\n\t\treturn fromRequest as Language;\n\t}\n\tif (typeof localStorage !== 'undefined') {\n\t\tconst stored = localStorage.getItem(LANGUAGE_KEY);\n\t\tif (SUPPORTED_LANGUAGES.includes(stored as Language)) {\n\t\t\treturn stored as Language;\n\t\t}\n\t}\n\treturn FALLBACK_LANGUAGE;\n}\n\nexport function createTranslator<K extends string = LocaleKey>(\n\tresources: Record<string, any> = {},\n\tlocaleProvider: LanguageProvider = getLanguage,\n) {\n\treturn (\n\t\tkey: K,\n\t\tcontext: TranslationContext = undefined,\n\t\tprovideLanguage: LanguageProvider = localeProvider,\n\t): string => {\n\t\tconst language =\n\t\t\ttypeof provideLanguage === 'function'\n\t\t\t\t? provideLanguage()\n\t\t\t\t: provideLanguage;\n\t\tlet message: string = _.get(resources[language], key) ?? key;\n\t\ttry {\n\t\t\tmessage = new IntlMessageFormat(message, language).format(context);\n\t\t} catch (e) {\n\t\t\tconsole.error(e);\n\t\t}\n\n\t\treturn message;\n\t};\n}\n\nexport const translate = createTranslator(resources);\n"
   ],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAKO,IAAM,KAAK;AAAA,KACd;AAAA,EACH;AAAA,EACA;AAAA,EACA;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACLO,IAAM,KAAK;AAAA,KACd;AAAA,EACH;AAAA,EACA;AAAA,EACA;AACD;;;ACPO,IAAM,YAAY;AAAA,EACxB;AAAA,EACA;AACD;;;ACHO,IAAM,eAAe;AAErB,IAAM,sBAAsB,OAAO,KAAK,SAAS;AAEjD,IAAM,oBAA8B;;ACP3C;AACA;AACA;AAsBO,SAAS,WAAW,GAAa;AAAA,EACvC,MAAM,cAAuB,cAAc,GAAG,IAAI,YAAqB;AAAA,EACvE,IACC,OAAO,gBAAgB,YACvB,oBAAoB,SAAS,WAAuB,GACnD;AAAA,IACD,OAAO;AAAA,EACR;AAAA,EACA,IAAI,OAAO,iBAAiB,aAAa;AAAA,IACxC,MAAM,SAAS,aAAa,QAAQ,YAAY;AAAA,IAChD,IAAI,oBAAoB,SAAS,MAAkB,GAAG;AAAA,MACrD,OAAO;AAAA,IACR;AAAA,EACD;AAAA,EACA,OAAO;AAAA;AAGD,SAAS,gBAA8C,CAC7D,aAAiC,CAAC,GAClC,iBAAmC,aAClC;AAAA,EACD,OAAO,CACN,KACA,UAA8B,WAC9B,kBAAoC,mBACxB;AAAA,IACZ,MAAM,WACL,OAAO,oBAAoB,aACxB,gBAAgB,IAChB;AAAA,IACJ,IAAI,UAAkB,EAAE,IAAI,WAAU,WAAW,GAAG,KAAK;AAAA,IACzD,IAAI;AAAA,MACH,UAAU,IAAI,kBAAkB,SAAS,QAAQ,EAAE,OAAO,OAAO;AAAA,MAChE,OAAO,GAAG;AAAA,MACX,QAAQ,MAAM,CAAC;AAAA;AAAA,IAGhB,OAAO;AAAA;AAAA;AAIF,IAAM,YAAY,iBAAiB,SAAS;",
-  "debugId": "629CBE18E4850F3E64756E2164756E21",
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAKO,IAAM,KAAK;AAAA,KACd;AAAA,EACH;AAAA,EACA;AAAA,EACA;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACLO,IAAM,KAAK;AAAA,KACd;AAAA,EACH;AAAA,EACA;AAAA,EACA;AACD;;;ACPO,IAAM,YAAY;AAAA,EACxB;AAAA,EACA;AACD;;;ACHO,IAAM,eAAe;AAErB,IAAM,sBAAsB,OAAO,KAAK,SAAS;AAEjD,IAAM,oBAA8B;;ACP3C;AACA;AACA;AAsBO,SAAS,WAAW,GAAa;AAAA,EACvC,MAAM,cAAuB,cAAc,GAAG,IAAI,YAAqB;AAAA,EACvE,IACC,OAAO,gBAAgB,YACvB,oBAAoB,SAAS,WAAuB,GACnD;AAAA,IACD,OAAO;AAAA,EACR;AAAA,EACA,IAAI,OAAO,iBAAiB,aAAa;AAAA,IACxC,MAAM,SAAS,aAAa,QAAQ,YAAY;AAAA,IAChD,IAAI,oBAAoB,SAAS,MAAkB,GAAG;AAAA,MACrD,OAAO;AAAA,IACR;AAAA,EACD;AAAA,EACA,OAAO;AAAA;AAGD,SAAS,gBAA8C,CAC7D,YAAiC,CAAC,GAClC,iBAAmC,aAClC;AAAA,EACD,OAAO,CACN,KACA,UAA8B,WAC9B,kBAAoC,mBACxB;AAAA,IACZ,MAAM,WACL,OAAO,oBAAoB,aACxB,gBAAgB,IAChB;AAAA,IACJ,IAAI,UAAkB,EAAE,IAAI,UAAU,WAAW,GAAG,KAAK;AAAA,IACzD,IAAI;AAAA,MACH,UAAU,IAAI,kBAAkB,SAAS,QAAQ,EAAE,OAAO,OAAO;AAAA,MAChE,OAAO,GAAG;AAAA,MACX,QAAQ,MAAM,CAAC;AAAA;AAAA,IAGhB,OAAO;AAAA;AAAA;AAIF,IAAM,YAAY,iBAAiB,SAAS;",
+  "debugId": "9824428B699DC6DF64756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/i18n",
-	"version": "1.0.1",
+	"version": "1.0.3",
 	"license": "UNLICENSED",
 	"type": "module",
 	"main": "./dist/index.js",