@nxgt/i18n 1.0.2 → 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +53 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -17,3 +17,56 @@ bun add @nxgt/i18n
|
|
|
17
17
|
Public on npmjs; no token needed to install. TypeScript is a peer, pinned to
|
|
18
18
|
`^6.0.3` across every `@nxgt/*` package — the set is unsatisfiable if one of
|
|
19
19
|
them widens it.
|
|
20
|
+
|
|
21
|
+
## Usage
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import {
|
|
25
|
+
createTranslator,
|
|
26
|
+
getLanguage,
|
|
27
|
+
translate,
|
|
28
|
+
FALLBACK_LANGUAGE,
|
|
29
|
+
SUPPORTED_LANGUAGES,
|
|
30
|
+
LANGUAGE_KEY,
|
|
31
|
+
} from '@nxgt/i18n';
|
|
32
|
+
|
|
33
|
+
translate('errors.not-found');
|
|
34
|
+
|
|
35
|
+
const t = createTranslator(myCatalogues, getLanguage);
|
|
36
|
+
t('users.greeting', { name });
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`translate` is bound to this package's catalogues (`en` and `fr`, under
|
|
40
|
+
`errors`, `common`, `validation`, `zod`). Pass your own catalogues to
|
|
41
|
+
`createTranslator` when a service has messages this package does not. A missing
|
|
42
|
+
key returns the key itself, not a throw.
|
|
43
|
+
|
|
44
|
+
`LocaleKey` is `keyof` the flattened English catalogue — that is the type
|
|
45
|
+
`CustomException.message` uses. `Language` is `'en' | 'fr'`. `resources`,
|
|
46
|
+
`en` and `fr` are the catalogues themselves. Shared keys include
|
|
47
|
+
`errors.not-found`, `errors.unauthenticated`, `errors.insufficient-permissions`
|
|
48
|
+
and `errors.service-unavailable`.
|
|
49
|
+
|
|
50
|
+
## Where the language comes from
|
|
51
|
+
|
|
52
|
+
`getLanguage()` asks, most specific first:
|
|
53
|
+
|
|
54
|
+
1. the Hono request context (`LANGUAGE_KEY`, `'language'`)
|
|
55
|
+
2. `localStorage.language`, when that object exists
|
|
56
|
+
3. `FALLBACK_LANGUAGE` (`'en'`)
|
|
57
|
+
|
|
58
|
+
The two consuming monorepos had forked exactly this — one read the request, the
|
|
59
|
+
other read `localStorage` — and neither could run where the other did. Asking
|
|
60
|
+
both serves either without a caller changing anything. Pass a provider (a
|
|
61
|
+
function or a `Language` literal) to `createTranslator` if you want one source
|
|
62
|
+
and not the other.
|
|
63
|
+
|
|
64
|
+
`SUPPORTED_LANGUAGES` is derived from the catalogue keys, not typed out.
|
|
65
|
+
|
|
66
|
+
## Things that bite
|
|
67
|
+
|
|
68
|
+
- **Messages are keys.** Rendering at the throw site (or translating in a
|
|
69
|
+
service) freezes the language of whoever threw, not of whoever reads.
|
|
70
|
+
- **ICU formatting failures are swallowed** (`console.error`) and the
|
|
71
|
+
unformatted message is returned. A bad `{name}` in a catalogue is a log
|
|
72
|
+
line, not a 500.
|