@abinnovision/nestjs-i18n 0.1.0-beta.2 → 0.1.0-beta.5
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 +44 -0
- package/dist/exceptions/exception-messages.d.cts +19 -1
- package/dist/exceptions/exception-messages.d.mts +19 -1
- package/dist/exceptions.d.cts +2 -2
- package/dist/exceptions.d.mts +2 -2
- package/dist/i18n.middleware.cjs +7 -7
- package/dist/i18n.middleware.mjs +7 -7
- package/dist/i18n.module.cjs +1 -1
- package/dist/i18n.module.mjs +1 -1
- package/dist/i18n.service.cjs +8 -0
- package/dist/i18n.service.d.cts +12 -3
- package/dist/i18n.service.d.mts +12 -3
- package/dist/i18n.service.mjs +8 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -65,6 +65,8 @@ export class AppModule {}
|
|
|
65
65
|
|
|
66
66
|
`forRootAsync({ inject, useFactory })` is available as well. The module throws at startup when `defaultLocale` has no catalog.
|
|
67
67
|
|
|
68
|
+
`I18nModule` shares its name with the NestJS i18n packages. Alias the import (`import { I18nModule as NestI18nModule }`) or name your own module differently, e.g. `LocalizationModule`.
|
|
69
|
+
|
|
68
70
|
### 4. Translate
|
|
69
71
|
|
|
70
72
|
```typescript
|
|
@@ -82,6 +84,17 @@ The locale is taken from `opts.locale`, then from `i18n.run(locale, fn)`, then r
|
|
|
82
84
|
|
|
83
85
|
Set `middleware: false` to disable the request context middleware. Then only an explicit `locale` and `run()` apply.
|
|
84
86
|
|
|
87
|
+
### Handlers outside Nest
|
|
88
|
+
|
|
89
|
+
Handlers registered on the raw HTTP adapter (e.g. better-auth) run outside the middleware, whether or not `middleware: false` is set. Wrap them with `runForRequest`:
|
|
90
|
+
|
|
91
|
+
```typescript
|
|
92
|
+
const i18n = app.get(I18nService);
|
|
93
|
+
app.use((req, _res, next) => i18n.runForRequest(req, next));
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Register it before those handlers. `app.get(I18nService)` works because the module is global. The locale is still resolved from the request on every call. Callbacks from streams or `EventEmitter`s can lose the async context, same as with the middleware.
|
|
97
|
+
|
|
85
98
|
## Localized exceptions
|
|
86
99
|
|
|
87
100
|
With `@abinnovision/nestjs-exceptions`, the `./exceptions` subpath localizes the `detail` of error responses with the `exceptions.<CODE>` messages. The exception `meta` is used as message parameters. Entity-focused exceptions also get an `entity` parameter from the `entities.<name>` message, or the raw entity name.
|
|
@@ -115,6 +128,35 @@ export class AppModule {}
|
|
|
115
128
|
|
|
116
129
|
Codes without a message keep the English `details`.
|
|
117
130
|
|
|
131
|
+
### Exception coverage
|
|
132
|
+
|
|
133
|
+
`ExceptionsOf` turns the exports of a module into the union of its exception classes, so a new class is covered once it is exported:
|
|
134
|
+
|
|
135
|
+
```typescript
|
|
136
|
+
import type * as userExceptions from "./user.exceptions.js";
|
|
137
|
+
|
|
138
|
+
export const en = defineCatalog({
|
|
139
|
+
...defaultExceptionMessages,
|
|
140
|
+
"exceptions.USER__EMAIL_TAKEN": "Email ''{email}'' is already taken",
|
|
141
|
+
}) satisfies ExceptionMessages<ExceptionsOf<typeof userExceptions>>;
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Only exported exception classes with a literal `code` count. Non-exception exports and bases with a wide `code: string` are excluded.
|
|
145
|
+
|
|
146
|
+
### Entity messages
|
|
147
|
+
|
|
148
|
+
`EntityMessages` requires an `entities.<name>` message per entity name. Combine it with `ExceptionMessages` using `&`:
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
export const en = defineCatalog({
|
|
152
|
+
...defaultExceptionMessages,
|
|
153
|
+
"entities.user": "User",
|
|
154
|
+
}) satisfies ExceptionMessages<ExceptionsOf<typeof userExceptions>> &
|
|
155
|
+
EntityMessages;
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
It checks nothing until `EntityRegistry` is augmented. Use `EntityMessages<"user" | "org">` to name the entities explicitly.
|
|
159
|
+
|
|
118
160
|
## Testing
|
|
119
161
|
|
|
120
162
|
```typescript
|
|
@@ -125,4 +167,6 @@ it("has complete catalogs", () => {
|
|
|
125
167
|
});
|
|
126
168
|
```
|
|
127
169
|
|
|
170
|
+
Missing messages: `CatalogShape` enforces keys only when `I18nRegistry` is augmented and the catalogs are not cast. `verifyCatalogs` covers the rest in tests. At runtime, a fallback from a non-default locale is logged at debug level, which is visible when debug logging is enabled (the default with Nest's `ConsoleLogger`).
|
|
171
|
+
|
|
128
172
|
`verifyCatalogs` reports missing keys, extra keys, messages that fail to parse, and arguments that the default-locale message does not have (for example a `{nmae}` typo).
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { AppExceptionClass, ExceptionCode } from "@abinnovision/nestjs-exceptions";
|
|
2
|
+
import { EntityName } from "@abinnovision/nestjs-exceptions/entity";
|
|
2
3
|
|
|
3
4
|
//#region src/exceptions/exception-messages.d.ts
|
|
4
5
|
/**
|
|
@@ -16,5 +17,22 @@ import { AppExceptionClass, ExceptionCode } from "@abinnovision/nestjs-exception
|
|
|
16
17
|
* ```
|
|
17
18
|
*/
|
|
18
19
|
type ExceptionMessages<E extends AppExceptionClass> = { [K in `exceptions.${ExceptionCode<E>}`]: string };
|
|
20
|
+
/**
|
|
21
|
+
* The exception classes among the exports of a module type. Excludes
|
|
22
|
+
* non-exception exports and classes whose `code` is not a literal.
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* ```typescript
|
|
26
|
+
* import type * as userExceptions from "./user.exceptions.js";
|
|
27
|
+
*
|
|
28
|
+
* type Messages = ExceptionMessages<ExceptionsOf<typeof userExceptions>>;
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
31
|
+
type ExceptionsOf<M> = { [K in keyof M]: M[K] extends AppExceptionClass ? string extends ExceptionCode<M[K]> ? never : M[K] : never }[keyof M];
|
|
32
|
+
/**
|
|
33
|
+
* Requires an `entities.<name>` message per entity name. Requires nothing
|
|
34
|
+
* while `EntityRegistry` is not augmented.
|
|
35
|
+
*/
|
|
36
|
+
type EntityMessages<E extends string = EntityName> = string extends E ? Record<never, never> : { [K in `entities.${E}`]: string };
|
|
19
37
|
//#endregion
|
|
20
|
-
export { ExceptionMessages };
|
|
38
|
+
export { EntityMessages, ExceptionMessages, ExceptionsOf };
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { AppExceptionClass, ExceptionCode } from "@abinnovision/nestjs-exceptions";
|
|
2
|
+
import { EntityName } from "@abinnovision/nestjs-exceptions/entity";
|
|
2
3
|
|
|
3
4
|
//#region src/exceptions/exception-messages.d.ts
|
|
4
5
|
/**
|
|
@@ -16,5 +17,22 @@ import { AppExceptionClass, ExceptionCode } from "@abinnovision/nestjs-exception
|
|
|
16
17
|
* ```
|
|
17
18
|
*/
|
|
18
19
|
type ExceptionMessages<E extends AppExceptionClass> = { [K in `exceptions.${ExceptionCode<E>}`]: string };
|
|
20
|
+
/**
|
|
21
|
+
* The exception classes among the exports of a module type. Excludes
|
|
22
|
+
* non-exception exports and classes whose `code` is not a literal.
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* ```typescript
|
|
26
|
+
* import type * as userExceptions from "./user.exceptions.js";
|
|
27
|
+
*
|
|
28
|
+
* type Messages = ExceptionMessages<ExceptionsOf<typeof userExceptions>>;
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
31
|
+
type ExceptionsOf<M> = { [K in keyof M]: M[K] extends AppExceptionClass ? string extends ExceptionCode<M[K]> ? never : M[K] : never }[keyof M];
|
|
32
|
+
/**
|
|
33
|
+
* Requires an `entities.<name>` message per entity name. Requires nothing
|
|
34
|
+
* while `EntityRegistry` is not augmented.
|
|
35
|
+
*/
|
|
36
|
+
type EntityMessages<E extends string = EntityName> = string extends E ? Record<never, never> : { [K in `entities.${E}`]: string };
|
|
19
37
|
//#endregion
|
|
20
|
-
export { ExceptionMessages };
|
|
38
|
+
export { EntityMessages, ExceptionMessages, ExceptionsOf };
|
package/dist/exceptions.d.cts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
import { I18nExceptionLocalizer } from "./exceptions/i18n-exception-localizer.cjs";
|
|
2
2
|
import { defaultExceptionMessages } from "./exceptions/default-messages.cjs";
|
|
3
|
-
import { ExceptionMessages } from "./exceptions/exception-messages.cjs";
|
|
4
|
-
export { ExceptionMessages, I18nExceptionLocalizer, defaultExceptionMessages };
|
|
3
|
+
import { EntityMessages, ExceptionMessages, ExceptionsOf } from "./exceptions/exception-messages.cjs";
|
|
4
|
+
export { EntityMessages, ExceptionMessages, ExceptionsOf, I18nExceptionLocalizer, defaultExceptionMessages };
|
package/dist/exceptions.d.mts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
import { I18nExceptionLocalizer } from "./exceptions/i18n-exception-localizer.mjs";
|
|
2
2
|
import { defaultExceptionMessages } from "./exceptions/default-messages.mjs";
|
|
3
|
-
import { ExceptionMessages } from "./exceptions/exception-messages.mjs";
|
|
4
|
-
export { ExceptionMessages, I18nExceptionLocalizer, defaultExceptionMessages };
|
|
3
|
+
import { EntityMessages, ExceptionMessages, ExceptionsOf } from "./exceptions/exception-messages.mjs";
|
|
4
|
+
export { EntityMessages, ExceptionMessages, ExceptionsOf, I18nExceptionLocalizer, defaultExceptionMessages };
|
package/dist/i18n.middleware.cjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
const
|
|
1
|
+
const require_i18n_service = require("./i18n.service.cjs");
|
|
2
2
|
let _nestjs_common = require("@nestjs/common");
|
|
3
3
|
//#region src/i18n.middleware.ts
|
|
4
4
|
function _ts_decorate(decorators, target, key, desc) {
|
|
@@ -16,19 +16,19 @@ function _ts_param(paramIndex, decorator) {
|
|
|
16
16
|
};
|
|
17
17
|
}
|
|
18
18
|
var I18nMiddleware = class {
|
|
19
|
-
|
|
20
|
-
constructor(
|
|
21
|
-
this.
|
|
19
|
+
i18n;
|
|
20
|
+
constructor(i18n) {
|
|
21
|
+
this.i18n = i18n;
|
|
22
22
|
}
|
|
23
23
|
use(request, _response, next) {
|
|
24
|
-
this.
|
|
24
|
+
this.i18n.runForRequest(request, next);
|
|
25
25
|
}
|
|
26
26
|
};
|
|
27
27
|
I18nMiddleware = _ts_decorate([
|
|
28
28
|
(0, _nestjs_common.Injectable)(),
|
|
29
|
-
_ts_param(0, (0, _nestjs_common.Inject)(
|
|
29
|
+
_ts_param(0, (0, _nestjs_common.Inject)(require_i18n_service.I18nService)),
|
|
30
30
|
_ts_metadata("design:type", Function),
|
|
31
|
-
_ts_metadata("design:paramtypes", [typeof
|
|
31
|
+
_ts_metadata("design:paramtypes", [typeof require_i18n_service.I18nService === "undefined" ? Object : require_i18n_service.I18nService])
|
|
32
32
|
], I18nMiddleware);
|
|
33
33
|
//#endregion
|
|
34
34
|
Object.defineProperty(exports, "I18nMiddleware", {
|
package/dist/i18n.middleware.mjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { I18nService } from "./i18n.service.mjs";
|
|
2
2
|
import { Inject, Injectable } from "@nestjs/common";
|
|
3
3
|
//#region src/i18n.middleware.ts
|
|
4
4
|
function _ts_decorate(decorators, target, key, desc) {
|
|
@@ -16,19 +16,19 @@ function _ts_param(paramIndex, decorator) {
|
|
|
16
16
|
};
|
|
17
17
|
}
|
|
18
18
|
var I18nMiddleware = class {
|
|
19
|
-
|
|
20
|
-
constructor(
|
|
21
|
-
this.
|
|
19
|
+
i18n;
|
|
20
|
+
constructor(i18n) {
|
|
21
|
+
this.i18n = i18n;
|
|
22
22
|
}
|
|
23
23
|
use(request, _response, next) {
|
|
24
|
-
this.
|
|
24
|
+
this.i18n.runForRequest(request, next);
|
|
25
25
|
}
|
|
26
26
|
};
|
|
27
27
|
I18nMiddleware = _ts_decorate([
|
|
28
28
|
Injectable(),
|
|
29
|
-
_ts_param(0, Inject(
|
|
29
|
+
_ts_param(0, Inject(I18nService)),
|
|
30
30
|
_ts_metadata("design:type", Function),
|
|
31
|
-
_ts_metadata("design:paramtypes", [typeof
|
|
31
|
+
_ts_metadata("design:paramtypes", [typeof I18nService === "undefined" ? Object : I18nService])
|
|
32
32
|
], I18nMiddleware);
|
|
33
33
|
//#endregion
|
|
34
34
|
export { I18nMiddleware };
|
package/dist/i18n.module.cjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
const require_i18n_module_config = require("./i18n.module-config.cjs");
|
|
2
2
|
const require_i18n_context = require("./i18n.context.cjs");
|
|
3
|
-
const require_i18n_middleware = require("./i18n.middleware.cjs");
|
|
4
3
|
const require_i18n_service = require("./i18n.service.cjs");
|
|
4
|
+
const require_i18n_middleware = require("./i18n.middleware.cjs");
|
|
5
5
|
let _nestjs_common = require("@nestjs/common");
|
|
6
6
|
//#region src/i18n.module.ts
|
|
7
7
|
function _ts_decorate(decorators, target, key, desc) {
|
package/dist/i18n.module.mjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { i18nModuleConfigToken } from "./i18n.module-config.mjs";
|
|
2
2
|
import { I18nContext } from "./i18n.context.mjs";
|
|
3
|
-
import { I18nMiddleware } from "./i18n.middleware.mjs";
|
|
4
3
|
import { I18nService } from "./i18n.service.mjs";
|
|
4
|
+
import { I18nMiddleware } from "./i18n.middleware.mjs";
|
|
5
5
|
import { ConfigurableModuleBuilder, Global, Inject, Module } from "@nestjs/common";
|
|
6
6
|
//#region src/i18n.module.ts
|
|
7
7
|
function _ts_decorate(decorators, target, key, desc) {
|
package/dist/i18n.service.cjs
CHANGED
|
@@ -57,6 +57,13 @@ var I18nService = class I18nService {
|
|
|
57
57
|
}, fn);
|
|
58
58
|
}
|
|
59
59
|
/**
|
|
60
|
+
* Runs `fn` in a new context holding the request. The locale is resolved
|
|
61
|
+
* from the request on every call. A locale set by an outer `run()` does
|
|
62
|
+
* not apply inside.
|
|
63
|
+
*/ runForRequest(request, fn) {
|
|
64
|
+
return this.context.run({ request }, fn);
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
60
67
|
* Resolves the locale of a request with the configured resolvers.
|
|
61
68
|
*/ resolveLocale(request) {
|
|
62
69
|
for (const resolver of this.resolvers) {
|
|
@@ -75,6 +82,7 @@ var I18nService = class I18nService {
|
|
|
75
82
|
let target = locale;
|
|
76
83
|
let message = catalogs[locale]?.[key];
|
|
77
84
|
if (message === void 0) {
|
|
85
|
+
if (locale !== this.config.defaultLocale) this.logger.debug(`Message '${key}' is missing in locale '${locale}'`);
|
|
78
86
|
target = this.config.defaultLocale;
|
|
79
87
|
message = catalogs[target]?.[key];
|
|
80
88
|
}
|
package/dist/i18n.service.d.cts
CHANGED
|
@@ -16,9 +16,12 @@ interface TranslateOptions {
|
|
|
16
16
|
/**
|
|
17
17
|
* Translates messages of the configured catalogs.
|
|
18
18
|
*
|
|
19
|
-
* The locale is taken from `opts.locale`, then from `run()`,
|
|
20
|
-
* from the
|
|
21
|
-
*
|
|
19
|
+
* The locale is taken from `opts.locale`, then from the innermost `run()`,
|
|
20
|
+
* then resolved from the request of the innermost `runForRequest()` or
|
|
21
|
+
* middleware context, then the default locale. Both `run()` and
|
|
22
|
+
* `runForRequest()` start a new context: `run()` keeps the outer request,
|
|
23
|
+
* `runForRequest()` drops the outer locale. The request locale is resolved
|
|
24
|
+
* on every call, so values set later in the request (e.g. `req.user`) apply.
|
|
22
25
|
*/
|
|
23
26
|
declare class I18nService {
|
|
24
27
|
private readonly config;
|
|
@@ -41,6 +44,12 @@ declare class I18nService {
|
|
|
41
44
|
* Runs `fn` with the given locale as the context locale.
|
|
42
45
|
*/
|
|
43
46
|
run<T>(locale: Locale, fn: () => T): T;
|
|
47
|
+
/**
|
|
48
|
+
* Runs `fn` in a new context holding the request. The locale is resolved
|
|
49
|
+
* from the request on every call. A locale set by an outer `run()` does
|
|
50
|
+
* not apply inside.
|
|
51
|
+
*/
|
|
52
|
+
runForRequest<T>(request: I18nRequest, fn: () => T): T;
|
|
44
53
|
/**
|
|
45
54
|
* Resolves the locale of a request with the configured resolvers.
|
|
46
55
|
*/
|
package/dist/i18n.service.d.mts
CHANGED
|
@@ -16,9 +16,12 @@ interface TranslateOptions {
|
|
|
16
16
|
/**
|
|
17
17
|
* Translates messages of the configured catalogs.
|
|
18
18
|
*
|
|
19
|
-
* The locale is taken from `opts.locale`, then from `run()`,
|
|
20
|
-
* from the
|
|
21
|
-
*
|
|
19
|
+
* The locale is taken from `opts.locale`, then from the innermost `run()`,
|
|
20
|
+
* then resolved from the request of the innermost `runForRequest()` or
|
|
21
|
+
* middleware context, then the default locale. Both `run()` and
|
|
22
|
+
* `runForRequest()` start a new context: `run()` keeps the outer request,
|
|
23
|
+
* `runForRequest()` drops the outer locale. The request locale is resolved
|
|
24
|
+
* on every call, so values set later in the request (e.g. `req.user`) apply.
|
|
22
25
|
*/
|
|
23
26
|
declare class I18nService {
|
|
24
27
|
private readonly config;
|
|
@@ -41,6 +44,12 @@ declare class I18nService {
|
|
|
41
44
|
* Runs `fn` with the given locale as the context locale.
|
|
42
45
|
*/
|
|
43
46
|
run<T>(locale: Locale, fn: () => T): T;
|
|
47
|
+
/**
|
|
48
|
+
* Runs `fn` in a new context holding the request. The locale is resolved
|
|
49
|
+
* from the request on every call. A locale set by an outer `run()` does
|
|
50
|
+
* not apply inside.
|
|
51
|
+
*/
|
|
52
|
+
runForRequest<T>(request: I18nRequest, fn: () => T): T;
|
|
44
53
|
/**
|
|
45
54
|
* Resolves the locale of a request with the configured resolvers.
|
|
46
55
|
*/
|
package/dist/i18n.service.mjs
CHANGED
|
@@ -57,6 +57,13 @@ var I18nService = class I18nService {
|
|
|
57
57
|
}, fn);
|
|
58
58
|
}
|
|
59
59
|
/**
|
|
60
|
+
* Runs `fn` in a new context holding the request. The locale is resolved
|
|
61
|
+
* from the request on every call. A locale set by an outer `run()` does
|
|
62
|
+
* not apply inside.
|
|
63
|
+
*/ runForRequest(request, fn) {
|
|
64
|
+
return this.context.run({ request }, fn);
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
60
67
|
* Resolves the locale of a request with the configured resolvers.
|
|
61
68
|
*/ resolveLocale(request) {
|
|
62
69
|
for (const resolver of this.resolvers) {
|
|
@@ -75,6 +82,7 @@ var I18nService = class I18nService {
|
|
|
75
82
|
let target = locale;
|
|
76
83
|
let message = catalogs[locale]?.[key];
|
|
77
84
|
if (message === void 0) {
|
|
85
|
+
if (locale !== this.config.defaultLocale) this.logger.debug(`Message '${key}' is missing in locale '${locale}'`);
|
|
78
86
|
target = this.config.defaultLocale;
|
|
79
87
|
message = catalogs[target]?.[key];
|
|
80
88
|
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/package.json",
|
|
3
3
|
"name": "@abinnovision/nestjs-i18n",
|
|
4
|
-
"version": "0.1.0-beta.
|
|
4
|
+
"version": "0.1.0-beta.5",
|
|
5
5
|
"description": "Type-safe backend i18n for NestJS with ICU MessageFormat catalogs, request locale resolution, and localized exceptions.",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"nestjs",
|
|
@@ -76,7 +76,7 @@
|
|
|
76
76
|
},
|
|
77
77
|
"devDependencies": {
|
|
78
78
|
"@abinnovision/eslint-config-base": "^3.4.1",
|
|
79
|
-
"@abinnovision/nestjs-exceptions": "^0.
|
|
79
|
+
"@abinnovision/nestjs-exceptions": "^0.2.1",
|
|
80
80
|
"@abinnovision/prettier-config": "^2.2.0",
|
|
81
81
|
"@arethetypeswrong/core": "^0.18.3",
|
|
82
82
|
"@nestjs/common": "^12.3.3",
|