@signature-kit/i18n 0.1.0

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/CHANGELOG.md ADDED
@@ -0,0 +1,6 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+
5
+ - Initial release for localized SignatureKit error-message resolution after the
6
+ retirement of `@signature-kit/core`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SignatureKit contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,57 @@
1
+ # @signature-kit/i18n
2
+
3
+ Localized display-message resolution for SignatureKit tagged errors.
4
+
5
+ ## Install
6
+
7
+ ```sh
8
+ bun add @signature-kit/i18n effect
9
+ ```
10
+
11
+ `effect` is a direct runtime dependency because the option and catalog contracts are Schema-backed.
12
+
13
+ ## Public surface
14
+
15
+ - `@signature-kit/i18n` — `LocalizedCatalogSchema`, `LocalizedMessageMap`, `ErrorMessageOptionsSchema`, `ErrorMessageFallbackCodeSchema`, `ErrorMessageLocaleSchema`, `errorMessageFallbackMessages`, and `errorMessage(error, options)`.
16
+
17
+ `errorMessage(error, options)` reads `_tag` and `code` structurally. Consumers do not need `instanceof`, `.code` helper wrappers, or reason-string matching.
18
+
19
+ Resolution order for a known code:
20
+
21
+ 1. `overrides[locale][code]`
22
+ 2. `catalogs[*][locale][code]`
23
+ 3. `overrides[fallbackLocale][code]`
24
+ 4. `catalogs[*][fallbackLocale][code]`
25
+ 5. generic fallback messages for the requested locale, fallback locale, then `en-US`
26
+
27
+ The default fallback locale is `en-US`.
28
+
29
+ ## Example
30
+
31
+ ```ts
32
+ import { errorMessage } from "@signature-kit/i18n";
33
+ import { signatureKitErrorMessages, type SignatureKitError } from "@signature-kit/signatures";
34
+
35
+ declare const error: SignatureKitError;
36
+
37
+ const message = errorMessage(error, {
38
+ locale: "pt-BR",
39
+ fallbackLocale: "en-US",
40
+ catalogs: [signatureKitErrorMessages],
41
+ overrides: {
42
+ "pt-BR": {
43
+ "signature-kit.WRONG_PASSWORD": "Senha inválida para este certificado.",
44
+ },
45
+ },
46
+ });
47
+ ```
48
+
49
+ ## Errors and i18n
50
+
51
+ This package is the display layer. Package-specific message catalogs remain beside their `TaggedErrorClass` definitions: `signatureKitErrorMessages`, `pdfErrorMessages`, `xmlErrorMessages`, `cmsErrorMessages`, `cryptoErrorMessages`, and `asn1ErrorMessages`.
52
+
53
+ Docs: <https://signaturekit.dev/en-US/docs/signing/errors>.
54
+
55
+ ## License
56
+
57
+ MIT. See `LICENSE`.
package/dist/i18n.d.ts ADDED
@@ -0,0 +1,27 @@
1
+ import { Schema } from "effect";
2
+ declare const LocalizedMessageMapSchema: Schema.$Record<Schema.String, Schema.String>;
3
+ export type LocalizedMessageMap = (typeof LocalizedMessageMapSchema)["Type"];
4
+ export declare const LocalizedCatalogSchema: Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.String>>;
5
+ export type LocalizedCatalog = (typeof LocalizedCatalogSchema)["Type"];
6
+ export declare const ErrorMessageOptionsSchema: Schema.Struct<{
7
+ readonly locale: Schema.String;
8
+ readonly catalogs: Schema.$Array<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.String>>>;
9
+ readonly fallbackLocale: Schema.optional<Schema.Literals<readonly ["en-US"]>>;
10
+ readonly overrides: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.String>>>;
11
+ }>;
12
+ export type ErrorMessageOptions = (typeof ErrorMessageOptionsSchema)["Type"];
13
+ export declare const ErrorMessageFallbackCodeSchema: Schema.Literals<readonly ["i18n.GENERIC_ERROR"]>;
14
+ export type ErrorMessageFallbackCode = (typeof ErrorMessageFallbackCodeSchema)["Type"];
15
+ export declare const ErrorMessageLocaleSchema: Schema.Literals<readonly ["en-US", "pt-BR"]>;
16
+ export type ErrorMessageLocale = (typeof ErrorMessageLocaleSchema)["Type"];
17
+ export declare const errorMessageFallbackMessages: {
18
+ "en-US": {
19
+ "i18n.GENERIC_ERROR": string;
20
+ };
21
+ "pt-BR": {
22
+ "i18n.GENERIC_ERROR": string;
23
+ };
24
+ };
25
+ export declare const errorMessage: (error: unknown, options: ErrorMessageOptions) => string;
26
+ export {};
27
+ //# sourceMappingURL=i18n.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExC,QAAA,MAAM,yBAAyB,8CAA8C,CAAC;AAC9E,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,eAAO,MAAM,sBAAsB,6EAA0D,CAAC;AAC9F,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAIvE,eAAO,MAAM,yBAAyB;;;;;EAKpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAO7E,eAAO,MAAM,8BAA8B,kDAA0C,CAAC;AACtF,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvF,eAAO,MAAM,wBAAwB,8CAAsC,CAAC;AAC5E,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAM3E,eAAO,MAAM,4BAA4B;;;;;;;CAOD,CAAC;AAuBzC,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,EAAE,SAAS,mBAAmB,KAAG,MA6C3E,CAAC"}
package/dist/i18n.js ADDED
@@ -0,0 +1,70 @@
1
+ import { Result, Schema } from "effect";
2
+ const LocalizedMessageMapSchema = Schema.Record(Schema.String, Schema.String);
3
+ export const LocalizedCatalogSchema = Schema.Record(Schema.String, LocalizedMessageMapSchema);
4
+ const ErrorMessageFallbackLocaleSchema = Schema.Literals(["en-US"]);
5
+ export const ErrorMessageOptionsSchema = Schema.Struct({
6
+ locale: Schema.String,
7
+ catalogs: Schema.Array(LocalizedCatalogSchema),
8
+ fallbackLocale: Schema.optional(ErrorMessageFallbackLocaleSchema),
9
+ overrides: Schema.optional(LocalizedCatalogSchema),
10
+ });
11
+ const TaggedErrorShapeSchema = Schema.Struct({
12
+ _tag: Schema.String,
13
+ code: Schema.String,
14
+ });
15
+ export const ErrorMessageFallbackCodeSchema = Schema.Literals(["i18n.GENERIC_ERROR"]);
16
+ export const ErrorMessageLocaleSchema = Schema.Literals(["en-US", "pt-BR"]);
17
+ export const errorMessageFallbackMessages = {
18
+ "en-US": {
19
+ "i18n.GENERIC_ERROR": "Something went wrong.",
20
+ },
21
+ "pt-BR": {
22
+ "i18n.GENERIC_ERROR": "Algo deu errado.",
23
+ },
24
+ };
25
+ const localizedErrorMessageFallbacks = errorMessageFallbackMessages;
26
+ const getMessageFromCatalog = (catalog, locale, code) => {
27
+ if (!Object.hasOwn(catalog, locale)) {
28
+ return undefined;
29
+ }
30
+ const messages = catalog[locale];
31
+ if (messages === undefined) {
32
+ return undefined;
33
+ }
34
+ return Object.hasOwn(messages, code) ? messages[code] : undefined;
35
+ };
36
+ const genericErrorCode = "i18n.GENERIC_ERROR";
37
+ export const errorMessage = (error, options) => {
38
+ const validOptions = Result.getOrThrow(Schema.decodeUnknownResult(ErrorMessageOptionsSchema)(options));
39
+ const fallbackLocale = validOptions.fallbackLocale ?? "en-US";
40
+ const code = Schema.is(TaggedErrorShapeSchema)(error) ? error.code : undefined;
41
+ const overrides = validOptions.overrides;
42
+ if (code !== undefined) {
43
+ const explicitOverride = overrides === undefined
44
+ ? undefined
45
+ : getMessageFromCatalog(overrides, validOptions.locale, code);
46
+ if (explicitOverride !== undefined) {
47
+ return explicitOverride;
48
+ }
49
+ for (const catalog of validOptions.catalogs) {
50
+ const catalogMessage = getMessageFromCatalog(catalog, validOptions.locale, code);
51
+ if (catalogMessage !== undefined) {
52
+ return catalogMessage;
53
+ }
54
+ }
55
+ const fallbackLocaleOverride = overrides === undefined ? undefined : getMessageFromCatalog(overrides, fallbackLocale, code);
56
+ if (fallbackLocaleOverride !== undefined) {
57
+ return fallbackLocaleOverride;
58
+ }
59
+ for (const catalog of validOptions.catalogs) {
60
+ const fallbackCatalogMessage = getMessageFromCatalog(catalog, fallbackLocale, code);
61
+ if (fallbackCatalogMessage !== undefined) {
62
+ return fallbackCatalogMessage;
63
+ }
64
+ }
65
+ }
66
+ return (getMessageFromCatalog(localizedErrorMessageFallbacks, validOptions.locale, genericErrorCode) ??
67
+ getMessageFromCatalog(localizedErrorMessageFallbacks, fallbackLocale, genericErrorCode) ??
68
+ getMessageFromCatalog(localizedErrorMessageFallbacks, "en-US", genericErrorCode) ??
69
+ "Something went wrong.");
70
+ };
package/package.json ADDED
@@ -0,0 +1,58 @@
1
+ {
2
+ "name": "@signature-kit/i18n",
3
+ "version": "0.1.0",
4
+ "license": "MIT",
5
+ "files": [
6
+ "dist",
7
+ "README.md",
8
+ "LICENSE",
9
+ "CHANGELOG.md"
10
+ ],
11
+ "type": "module",
12
+ "sideEffects": false,
13
+ "main": "./dist/i18n.js",
14
+ "types": "./dist/i18n.d.ts",
15
+ "exports": {
16
+ ".": {
17
+ "types": "./dist/i18n.d.ts",
18
+ "import": "./dist/i18n.js"
19
+ }
20
+ },
21
+ "publishConfig": {
22
+ "access": "public"
23
+ },
24
+ "scripts": {
25
+ "build": "tsc -b tsconfig.json",
26
+ "typecheck": "tsc -p tsconfig.json --noEmit",
27
+ "test": "vitest run"
28
+ },
29
+ "dependencies": {
30
+ "effect": "4.0.0-beta.86"
31
+ },
32
+ "devDependencies": {
33
+ "@signature-kit/crypto": "^0.2.1",
34
+ "@signature-kit/signatures": "^0.1.0"
35
+ },
36
+ "nx": {
37
+ "implicitDependencies": [
38
+ "!@signature-kit/signatures",
39
+ "!@signature-kit/crypto"
40
+ ],
41
+ "targets": {
42
+ "npm-pack": {
43
+ "executor": "nx:run-commands",
44
+ "options": {
45
+ "command": "npm pack --dry-run --json",
46
+ "cwd": "{projectRoot}"
47
+ }
48
+ },
49
+ "npm-publish": {
50
+ "executor": "nx:run-commands",
51
+ "options": {
52
+ "command": "npm publish --access public",
53
+ "cwd": "{projectRoot}"
54
+ }
55
+ }
56
+ }
57
+ }
58
+ }