@dws-std/i18n 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominus Web Services (DWS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# 🌐 DWS I18n
+
+Type-safe internationalization for TypeScript.
+Define your translation catalogs once, and get localized messages and HTTP exceptions with full traceability, all validated at compile time.
+
+## Why this package?
+
+Internationalization is often treated as an afterthought, strings scattered across files, parameters interpolated by hand, no type safety.  
+This package takes a different approach: you declare structured catalogs with `entry()`, and the compiler does the rest.  
+Parameters, locales, HTTP statuses, if something's wrong, you'll know before your code even runs.
+
+It also plays nicely with `@dws-std/error`. Exception catalogs produce `LocalizedHttpException` instances that carry translations,
+a UUID v7, and an HTTP status code, so your error handling stays consistent and traceable.
+
+## 📌 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Usage](#-usage)
+- [API Reference](#-api-reference)
+- [License](#-license)
+- [Contact](#-contact)
+
+## ✨ Features
+
+- 🔒 **Type-safe catalogs** : Parameters, locales, and HTTP status are all validated at compile time thanks to `entry()`.
+- 🌍 **Multi-locale** : Each entry holds all its translations; pick the right one at call-time.
+- 🚨 **Localized exceptions** : `defineExceptionCatalog` gives you factory functions that create `LocalizedHttpException` instances, complete with status codes and UUID tracking.
+- 💬 **Localized messages** : `defineMessageCatalog` does the same for plain messages : confirmations, notifications, anything that isn't an error.
+- 🔗 **Template interpolation** : Use `{{param}}` placeholders in translations; `resolveMessage` fills them in.
+- 🔍 **UUID v7 tracking** : Every exception inherits traceability from `@dws-std/error`.
+
+## 🔧 Installation
+
+```bash
+bun add @dws-std/i18n
+```
+
+> **Peer dependency:** `@dws-std/error` must be installed alongside.
+
+## ⚙️ Usage
+
+### Defining entries
+
+`entry()` is the building block. Give it a `status` and it becomes an exception entry; leave `status` out and it's a plain message entry.
+
+```ts
+import { entry } from '@dws-std/i18n';
+
+// This will produce a LocalizedHttpException when used in an exception catalog
+const unauthorized = entry({
+	status: 'UNAUTHORIZED',
+	translations: {
+		en: 'Invalid credentials',
+		fr: 'Identifiants invalides'
+	}
+});
+
+// This will produce a plain ResolvedMessage when used in a message catalog
+const welcome = entry<{ name: string }>({
+	translations: {
+		en: 'Welcome, {{name}}!',
+		fr: 'Bienvenue, {{name}} !'
+	}
+});
+```
+
+### Exception catalogs
+
+Group related exception entries under a namespace. Each key becomes a factory function you can call to throw a localized exception.
+
+```ts
+import { defineExceptionCatalog, entry } from '@dws-std/i18n';
+
+const AUTH_ERRORS = defineExceptionCatalog({
+	namespace: 'auth',
+	defaultLocale: 'en',
+	definitions: {
+		invalidCredentials: entry({
+			status: 'UNAUTHORIZED',
+			translations: {
+				en: 'Invalid credentials',
+				fr: 'Identifiants invalides'
+			}
+		}),
+		emailTaken: entry<{ email: string }>({
+			status: 'CONFLICT',
+			translations: {
+				en: 'Email "{{email}}" is already taken',
+				fr: 'L\'email "{{email}}" est déjà utilisé'
+			}
+		})
+	}
+});
+
+// Throws a LocalizedHttpException with status 401
+throw AUTH_ERRORS.invalidCredentials();
+
+// With parameters, type-checked, so you can't forget one
+throw AUTH_ERRORS.emailTaken({ email: 'user@example.com' });
+```
+
+### Message catalogs
+
+Same idea, but for things that aren't errors, success confirmations, notifications, labels, etc.
+
+```ts
+import { defineMessageCatalog, entry } from '@dws-std/i18n';
+
+const DNS_MESSAGES = defineMessageCatalog({
+	defaultLocale: 'en',
+	definitions: {
+		recordCreated: entry({
+			translations: {
+				en: 'DNS record created successfully',
+				fr: 'Enregistrement DNS créé avec succès'
+			}
+		})
+	}
+});
+
+const msg = DNS_MESSAGES.recordCreated();
+```
+
+### Resolving to a specific locale
+
+`resolveMessage` takes a `LocalizedHttpException` or a `ResolvedMessage` and returns the interpolated string for the locale you want.
+
+```ts
+import { resolveMessage } from '@dws-std/i18n';
+
+const error = AUTH_ERRORS.emailTaken({ email: 'a@b.com' });
+
+resolveMessage(error); // default locale → "Email "a@b.com" is already taken"
+resolveMessage(error, 'fr'); // → "L'email "a@b.com" est déjà utilisé"
+```
+
+## 📚 API Reference
+
+Full docs: [Dominus-Web-Service.github.io/packages](https://Dominus-Web-Service.github.io/packages/)
+
+## ⚖️ License
+
+MIT - Feel free to use it.
+
+## 📧 Contact
+
+- GitHub: [Dominus-Web-Service](https://github.com/Dominus-Web-Service/packages)

package/dist/entry.d.ts

@@ -0,0 +1,20 @@
+import type { HttpStatusCode, HttpStatusKey } from '@dws-std/error';
+import type { ExceptionEntry } from './exception/type/exception-entry';
+import type { MessageEntry } from './message/type/message-entry';
+/**
+ * Creates a single catalog entry for use inside `defineExceptionCatalog` or `defineMessageCatalog`.
+ *
+ * When `status` is included in the definition the return type narrows to
+ * {@link ExceptionEntry}; without it the return type is {@link MessageEntry}.
+ *
+ * @param definition - Translations (and optional status) for this entry.
+ *
+ * @returns The definition object, typed as either {@link ExceptionEntry} or {@link MessageEntry} based on the presence of `status`.
+ */
+export declare function entry<TParams extends Record<string, string> = Record<string, string>, TLocales extends string = string>(definition: {
+    readonly status: HttpStatusKey | HttpStatusCode;
+    readonly translations: Readonly<Record<TLocales, string>>;
+}): ExceptionEntry<TParams, TLocales>;
+export declare function entry<TParams extends Record<string, string> = Record<string, string>, TLocales extends string = string>(definition: {
+    readonly translations: Readonly<Record<TLocales, string>>;
+}): MessageEntry<TParams, TLocales>;

package/dist/exception/define-exception-catalog.d.ts

@@ -0,0 +1,30 @@
+import { LocalizedHttpException } from './localized-http-exception';
+import type { ExceptionEntry } from './type/exception-entry';
+export type ExceptionCatalog<TDefs extends Record<string, ExceptionEntry<any>>> = {
+    readonly [K in keyof TDefs]: TDefs[K] extends ExceptionEntry<infer P> ? [P] extends [Record<string, never>] ? () => LocalizedHttpException : (params: P) => LocalizedHttpException : never;
+};
+/**
+ * Configuration for {@link defineExceptionCatalog}.
+ *
+ * @template TDefs - Shape of the exception definitions map.
+ */
+export interface DefineExceptionCatalogOptions<TDefs extends Record<string, ExceptionEntry<any>>> {
+    /** Prefix prepended to every error code (e.g. `'dns'` → `'dns.invalidRecordType'`). */
+    readonly namespace: string;
+    /** Locale used to build the default `message` when no locale is specified. */
+    readonly defaultLocale: keyof TDefs[keyof TDefs]['translations'];
+    /** Map of exception definitions keyed by error name. */
+    readonly definitions: TDefs;
+}
+/**
+ * Builds a typed exception catalog from a set of {@link ExceptionEntry} definitions.
+ *
+ * Each key in `definitions` becomes a factory function that creates
+ * a {@link LocalizedHttpException} pre-filled with the right translations,
+ * HTTP status, and error code (`namespace.key`).
+ *
+ * @param options - Namespace, default locale, and exception definitions.
+ *
+ * @returns An object whose keys mirror `definitions`, each a factory function.
+ */
+export declare const defineExceptionCatalog: <const TDefs extends Record<string, ExceptionEntry<any>>>(options: DefineExceptionCatalogOptions<TDefs>) => ExceptionCatalog<TDefs>;

package/dist/exception/localized-http-exception.d.ts

@@ -0,0 +1,38 @@
+import { HttpException, type HttpExceptionOptions } from '@dws-std/error';
+import type { Translations } from '../type/translations';
+/**
+ * Options accepted by the {@link LocalizedHttpException} constructor.
+ *
+ * @template TCause - Type of the underlying cause.
+ */
+export interface LocalizedHttpExceptionOptions<TCause = unknown> extends HttpExceptionOptions<TCause> {
+    /** All available translations keyed by locale. */
+    readonly translations: Translations;
+    /** Parameter values to interpolate into `{{placeholder}}` tokens. */
+    readonly params?: Readonly<Record<string, string>> | undefined;
+    /** Locale used to build the default `message` string. */
+    readonly defaultLocale: string;
+}
+/**
+ * HTTP exception that carries translated messages.
+ *
+ * The `message` property is automatically resolved to the default locale.
+ * Use {@link resolveMessage} to get a translation in a different locale.
+ *
+ * @template TCause - Type of the underlying cause.
+ */
+export declare class LocalizedHttpException<const TCause = unknown> extends HttpException<TCause> {
+    /** All available translations keyed by locale. */
+    readonly translations: Translations;
+    /** Parameter values interpolated into `{{placeholder}}` tokens. */
+    readonly params: Readonly<Record<string, string>> | undefined;
+    /** Locale used to build the default `message` string. */
+    readonly defaultLocale: string;
+    /**
+     * Creates a new localized HTTP exception.
+     *
+     * @param code - Application-specific error code (e.g. `'dns.invalidRecordType'`).
+     * @param init - Translations, params, status, and cause.
+     */
+    constructor(code: string, init: LocalizedHttpExceptionOptions<TCause>);
+}

package/dist/exception/type/exception-entry.d.ts

@@ -0,0 +1,17 @@
+import type { HttpStatusCode, HttpStatusKey } from '@dws-std/error';
+/**
+ * Blueprint for a translatable HTTP exception.
+ *
+ * Used inside an exception catalog created with `defineExceptionCatalog`.
+ *
+ * @template TParams - Parameter placeholders the message expects (e.g. `{ field: string }`).
+ * @template TLocales - Locale keys that must be provided (e.g. `'en' | 'fr'`).
+ */
+export interface ExceptionEntry<TParams extends Record<string, string> = Record<string, string>, TLocales extends string = string> {
+    /** HTTP status to attach (key name like `'NOT_FOUND'` or numeric code like `404`). */
+    readonly status: HttpStatusKey | HttpStatusCode;
+    /** Translated error messages keyed by locale. */
+    readonly translations: Readonly<Record<TLocales, string>>;
+    /** Placeholder values to interpolate into the translated string. */
+    readonly params?: TParams;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { entry } from './entry';
+export { defineExceptionCatalog } from './exception/define-exception-catalog';
+export type { DefineExceptionCatalogOptions, ExceptionCatalog } from './exception/define-exception-catalog';
+export { LocalizedHttpException } from './exception/localized-http-exception';
+export type { LocalizedHttpExceptionOptions as LocalizedHttpExceptionInit } from './exception/localized-http-exception';
+export type { ExceptionEntry } from './exception/type/exception-entry';
+export { defineMessageCatalog } from './message/define-message-catalog';
+export type { DefineMessageCatalogOptions, MessageCatalog } from './message/define-message-catalog';
+export type { MessageEntry } from './message/type/message-entry';
+export type { ResolvedMessage } from './message/type/resolved-message';
+export { resolveMessage } from './resolve-message';
+export type { Translations } from './type/translations';

package/dist/index.js

@@ -0,0 +1,68 @@
+// @bun
+// src/entry.ts
+function entry(definition) {
+  return definition;
+}
+// src/exception/localized-http-exception.ts
+import { HttpException } from "@dws-std/error";
+
+// src/resolve-message.ts
+var _interpolate = (template, params) => template.replace(/\{\{(\w+)\}\}/g, (_, key) => params[key] ?? `{{${key}}}`);
+var resolveMessage = (target, locale) => target.params ? _interpolate(target.translations[locale ?? target.defaultLocale] ?? "", target.params) : target.translations[locale ?? target.defaultLocale] ?? "";
+
+// src/exception/localized-http-exception.ts
+class LocalizedHttpException extends HttpException {
+  translations;
+  params;
+  defaultLocale;
+  constructor(code, init) {
+    super(resolveMessage({
+      translations: init.translations,
+      params: init.params,
+      defaultLocale: init.defaultLocale
+    }), {
+      cause: init.cause,
+      status: init.status,
+      code
+    });
+    this.translations = init.translations;
+    this.params = init.params;
+    this.defaultLocale = init.defaultLocale;
+  }
+}
+
+// src/exception/define-exception-catalog.ts
+var defineExceptionCatalog = (options) => {
+  const { namespace, defaultLocale, definitions } = options;
+  const catalog = {};
+  for (const [key, def] of Object.entries(definitions)) {
+    const exceptionDef = def;
+    catalog[key] = (params = {}) => new LocalizedHttpException(`${namespace}.${key}`, {
+      status: exceptionDef.status,
+      translations: exceptionDef.translations,
+      params,
+      defaultLocale
+    });
+  }
+  return catalog;
+};
+// src/message/define-message-catalog.ts
+var defineMessageCatalog = (options) => {
+  const catalog = {};
+  for (const [key, def] of Object.entries(options.definitions)) {
+    const msgDef = def;
+    catalog[key] = (params = {}) => ({
+      translations: msgDef.translations,
+      params,
+      defaultLocale: options.defaultLocale
+    });
+  }
+  return catalog;
+};
+export {
+  resolveMessage,
+  entry,
+  defineMessageCatalog,
+  defineExceptionCatalog,
+  LocalizedHttpException
+};

package/dist/message/define-message-catalog.d.ts

@@ -0,0 +1,27 @@
+import type { MessageEntry } from './type/message-entry';
+import type { ResolvedMessage } from './type/resolved-message';
+export type MessageCatalog<TDefs extends Record<string, MessageEntry<any>>> = {
+    readonly [K in keyof TDefs]: TDefs[K] extends MessageEntry<infer P> ? [P] extends [Record<string, never>] ? () => ResolvedMessage : (params: P) => ResolvedMessage : never;
+};
+/**
+ * Configuration for {@link defineMessageCatalog}.
+ *
+ * @template TDefs - Shape of the message definitions map.
+ */
+export interface DefineMessageCatalogOptions<TDefs extends Record<string, MessageEntry<any>>> {
+    /** Locale used when no explicit locale is passed to `resolveMessage`. */
+    readonly defaultLocale: keyof TDefs[keyof TDefs]['translations'];
+    /** Map of message definitions keyed by message name. */
+    readonly definitions: TDefs;
+}
+/**
+ * Builds a typed message catalog from a set of {@link MessageEntry} definitions.
+ *
+ * Each key in `definitions` becomes a factory function that creates
+ * a {@link ResolvedMessage} pre-filled with the right translations and default locale.
+ *
+ * @param options - Default locale and message definitions.
+ *
+ * @returns An object whose keys mirror `definitions`, each a factory function.
+ */
+export declare const defineMessageCatalog: <TDefs extends Record<string, MessageEntry<any>>>(options: DefineMessageCatalogOptions<TDefs>) => MessageCatalog<TDefs>;

package/dist/message/type/message-entry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Blueprint for a translatable message.
+ *
+ * Used inside a message catalog created with `defineMessageCatalog`.
+ *
+ * @template TParams - Parameter placeholders the message expects (e.g. `{ domain: string }`).
+ * @template TLocales - Locale keys that must be provided (e.g. `'en' | 'fr'`).
+ */
+export interface MessageEntry<TParams extends Record<string, string> = Record<string, string>, TLocales extends string = string> {
+    /** Translated strings keyed by locale. */
+    readonly translations: Readonly<Record<TLocales, string>>;
+    /** Placeholder values to interpolate into the translated string. */
+    readonly params?: TParams;
+}

package/dist/message/type/resolved-message.d.ts

@@ -0,0 +1,15 @@
+import type { Translations } from '../../type/translations';
+/**
+ * Fully resolved message ready to be rendered.
+ *
+ * Returned by the factory functions generated by `defineMessageCatalog`.
+ * Pass it to {@link resolveMessage} to get the final string for a given locale.
+ */
+export interface ResolvedMessage {
+    /** All available translations keyed by locale. */
+    readonly translations: Translations;
+    /** Parameter values to interpolate into `{{placeholder}}` tokens. */
+    readonly params?: Readonly<Record<string, string>> | undefined;
+    /** Locale used when no explicit locale is passed to `resolveMessage`. */
+    readonly defaultLocale: string;
+}

package/dist/resolve-message.d.ts

@@ -0,0 +1,16 @@
+import type { LocalizedHttpException } from './exception/localized-http-exception';
+import type { ResolvedMessage } from './message/type/resolved-message';
+/**
+ * Turns a {@link ResolvedMessage} or {@link LocalizedHttpException} into
+ * a plain string for the requested locale.
+ *
+ * `{{placeholder}}` tokens are replaced with matching values from `target.params`.
+ * Falls back to `target.defaultLocale` when `locale` is omitted.
+ * Returns an empty string when the requested locale has no translation.
+ *
+ * @param target - Message or exception to resolve.
+ * @param locale - Desired locale (e.g. `'fr'`). Defaults to `target.defaultLocale`.
+ *
+ * @returns Translated string with placeholders interpolated.
+ */
+export declare const resolveMessage: (target: LocalizedHttpException | ResolvedMessage, locale?: string) => string;

package/dist/type/translations.d.ts

@@ -0,0 +1,2 @@
+/** A locale-to-text mapping (e.g. `{ en: 'Hello', fr: 'Bonjour' }`). */
+export type Translations = Readonly<Record<string, string>>;

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@dws-std/i18n",
+	"version": "1.0.0",
+	"description": "Type-safe i18n for TypeScript — define localized exception and message catalogs with compile-time validated parameters.",
+	"keywords": [
+		"bun",
+		"dws",
+		"exception",
+		"http-error",
+		"i18n",
+		"internationalization",
+		"l10n",
+		"localization",
+		"translation"
+	],
+	"license": "MIT",
+	"author": "Dominus Web Services (DWS)",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Dominus-Web-Service/std",
+		"directory": "packages/i18n"
+	},
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "bun builder.ts",
+		"docs": "bunx typedoc --tsconfig tsconfig.build.json",
+		"fmt:check": "oxfmt --check",
+		"fmt": "oxfmt",
+		"lint:fix": "oxlint --type-aware --type-check --fix ./src",
+		"lint:github": "oxlint --type-aware --type-check --format=github ./src",
+		"lint": "oxlint --type-aware --type-check ./src",
+		"test": "bun test --pass-with-no-tests --coverage"
+	},
+	"dependencies": {
+		"@dws-std/error": "^2.0.0"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.10",
+		"oxfmt": "^0.40.0",
+		"oxlint": "^1.55.0",
+		"oxlint-tsgolint": "^0.16.0",
+		"typescript": "^5.9.3"
+	},
+	"peerDependencies": {
+		"@dws-std/error": "^2.0.0"
+	}
+}