@hazeljs/i18n 0.2.0-alpha.1

package/dist/translation.loader.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TranslationLoader = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * Loads JSON translation files from a directory and returns a locale store.
+ *
+ * Each file must be named <locale>.json (e.g. en.json, fr.json, zh-TW.json).
+ * Nested objects in the JSON are kept as-is; key lookup via dot-notation is
+ * resolved at translation time inside I18nService.
+ *
+ * Synchronous I/O is intentional: HazelJS's DI container resolves providers
+ * synchronously, so async factories would result in a Promise being stored
+ * as the service instance rather than the resolved value.
+ */
+class TranslationLoader {
+    /**
+     * Read all *.json files from the given directory synchronously.
+     * Returns a Map keyed by locale code (the filename without extension).
+     */
+    static load(translationsPath) {
+        const store = new Map();
+        let entries;
+        try {
+            entries = (0, fs_1.readdirSync)(translationsPath);
+        }
+        catch {
+            // Directory does not exist — return an empty store so the service starts
+            // gracefully without translations (it will return keys as-is).
+            return store;
+        }
+        const jsonFiles = entries.filter((file) => (0, path_1.extname)(file) === '.json');
+        for (const file of jsonFiles) {
+            const locale = (0, path_1.basename)(file, '.json');
+            const filePath = (0, path_1.join)(translationsPath, file);
+            try {
+                const raw = (0, fs_1.readFileSync)(filePath, 'utf-8');
+                const translations = JSON.parse(raw);
+                store.set(locale, translations);
+            }
+            catch (err) {
+                // Skip malformed files rather than crashing the application.
+                const message = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[@hazeljs/i18n] Failed to load translation file "${filePath}": ${message}\n`);
+            }
+        }
+        return store;
+    }
+}
+exports.TranslationLoader = TranslationLoader;

package/dist/translation.loader.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=translation.loader.test.d.ts.map

package/dist/translation.loader.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation.loader.test.d.ts","sourceRoot":"","sources":["../src/translation.loader.test.ts"],"names":[],"mappings":""}

package/dist/translation.loader.test.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const translation_loader_1 = require("./translation.loader");
+jest.mock('fs', () => ({
+    readdirSync: jest.fn(),
+    readFileSync: jest.fn(),
+}));
+const fs_1 = require("fs");
+const mockReaddirSync = fs_1.readdirSync;
+const mockReadFileSync = fs_1.readFileSync;
+describe('TranslationLoader', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    describe('load()', () => {
+        it('returns an empty store when directory does not exist', () => {
+            mockReaddirSync.mockImplementation(() => {
+                throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+            });
+            const store = translation_loader_1.TranslationLoader.load('/nonexistent/path');
+            expect(store.size).toBe(0);
+        });
+        it('returns an empty store when directory is empty', () => {
+            mockReaddirSync.mockReturnValue([]);
+            const store = translation_loader_1.TranslationLoader.load('/empty/dir');
+            expect(store.size).toBe(0);
+        });
+        it('ignores non-JSON files', () => {
+            mockReaddirSync.mockReturnValue(['README.md', 'notes.txt']);
+            const store = translation_loader_1.TranslationLoader.load('/some/dir');
+            expect(store.size).toBe(0);
+            expect(mockReadFileSync).not.toHaveBeenCalled();
+        });
+        it('loads a single JSON file and stores translations by locale', () => {
+            mockReaddirSync.mockReturnValue(['en.json']);
+            mockReadFileSync.mockReturnValue('{"hello":"Hello","bye":"Goodbye"}');
+            const store = translation_loader_1.TranslationLoader.load('/translations');
+            expect(store.has('en')).toBe(true);
+            expect(store.get('en')).toEqual({ hello: 'Hello', bye: 'Goodbye' });
+        });
+        it('loads multiple JSON files into separate locale entries', () => {
+            mockReaddirSync.mockReturnValue(['en.json', 'fr.json']);
+            mockReadFileSync
+                .mockReturnValueOnce('{"hello":"Hello"}')
+                .mockReturnValueOnce('{"hello":"Bonjour"}');
+            const store = translation_loader_1.TranslationLoader.load('/translations');
+            expect(store.size).toBe(2);
+            expect(store.get('en')).toEqual({ hello: 'Hello' });
+            expect(store.get('fr')).toEqual({ hello: 'Bonjour' });
+        });
+        it('handles locale codes with hyphens (zh-TW.json)', () => {
+            mockReaddirSync.mockReturnValue(['zh-TW.json']);
+            mockReadFileSync.mockReturnValue('{"greeting":"你好"}');
+            const store = translation_loader_1.TranslationLoader.load('/translations');
+            expect(store.has('zh-TW')).toBe(true);
+        });
+        it('skips malformed JSON files and writes to stderr', () => {
+            const stderrSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+            mockReaddirSync.mockReturnValue(['en.json', 'bad.json']);
+            mockReadFileSync
+                .mockReturnValueOnce('{"ok":true}')
+                .mockReturnValueOnce('{ invalid json');
+            const store = translation_loader_1.TranslationLoader.load('/translations');
+            expect(store.has('en')).toBe(true);
+            expect(store.has('bad')).toBe(false);
+            expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('[@hazeljs/i18n]'));
+            stderrSpy.mockRestore();
+        });
+        it('writes non-Error exception to stderr as string', () => {
+            const stderrSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+            mockReaddirSync.mockReturnValue(['broken.json']);
+            mockReadFileSync.mockImplementation(() => {
+                throw 'string error';
+            });
+            const store = translation_loader_1.TranslationLoader.load('/translations');
+            expect(store.has('broken')).toBe(false);
+            expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('string error'));
+            stderrSpy.mockRestore();
+        });
+        it('loads nested translation objects', () => {
+            mockReaddirSync.mockReturnValue(['en.json']);
+            mockReadFileSync.mockReturnValue(JSON.stringify({ errors: { notFound: 'Not found', invalid: 'Invalid' } }));
+            const store = translation_loader_1.TranslationLoader.load('/translations');
+            expect(store.get('en')).toEqual({
+                errors: { notFound: 'Not found', invalid: 'Invalid' },
+            });
+        });
+    });
+});

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Supported locale detection strategies, in order of priority.
+ */
+export type LocaleDetectionStrategy = 'query' | 'cookie' | 'header';
+/**
+ * A flat or nested map of translation keys to values.
+ * Nested objects represent namespaced keys (e.g. "errors.notFound").
+ * Leaf values are translation strings, which may contain {placeholder} tokens
+ * and optional plural forms via a "one"/"other" sub-object.
+ */
+export type TranslationValue = string | {
+    one: string;
+    other: string;
+    [form: string]: string;
+} | {
+    [key: string]: TranslationValue;
+};
+export type TranslationMap = Record<string, TranslationValue>;
+/**
+ * In-memory store: locale → flat translation map.
+ */
+export type LocaleStore = Map<string, TranslationMap>;
+/**
+ * Options for interpolating variables and selecting plural forms.
+ */
+export interface TranslateOptions {
+    /**
+     * Used for plural rule selection.
+     */
+    count?: number;
+    /**
+     * Key-value pairs substituted into {placeholder} tokens.
+     */
+    vars?: Record<string, string | number>;
+    /**
+     * Override the locale for this single call.
+     */
+    locale?: string;
+}
+/**
+ * Configuration options for I18nModule.forRoot().
+ */
+export interface I18nOptions {
+    /**
+     * The locale used when no locale can be detected.
+     * @default 'en'
+     */
+    defaultLocale?: string;
+    /**
+     * The locale to fall back to when a key is missing in the requested locale.
+     * @default same as defaultLocale
+     */
+    fallbackLocale?: string;
+    /**
+     * Absolute or relative path to the directory containing JSON translation files.
+     * Files must be named <locale>.json (e.g. en.json, fr.json).
+     * @default './translations'
+     */
+    translationsPath?: string;
+    /**
+     * Ordered list of locale-detection strategies to apply per request.
+     * @default ['query', 'cookie', 'header']
+     */
+    detection?: LocaleDetectionStrategy[];
+    /**
+     * Name of the query-string parameter to check.
+     * @default 'lang'
+     */
+    queryParam?: string;
+    /**
+     * Name of the cookie to check.
+     * @default 'locale'
+     */
+    cookieName?: string;
+    /**
+     * Whether to register this module globally so it does not need to be
+     * imported in every feature module.
+     * @default true
+     */
+    isGlobal?: boolean;
+}
+/**
+ * Fully resolved options with all defaults applied.
+ */
+export type ResolvedI18nOptions = Required<I18nOptions>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GACtD;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAA;CAAE,CAAC;AAExC,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAEvC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,SAAS,CAAC,EAAE,uBAAuB,EAAE,CAAC;IAEtC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@hazeljs/i18n",
+  "version": "0.2.0-alpha.1",
+  "description": "Internationalization (i18n) module for HazelJS framework",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --coverage",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.50",
+    "@typescript-eslint/eslint-plugin": "^8.18.2",
+    "@typescript-eslint/parser": "^8.18.2",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hazel-js/hazeljs.git",
+    "directory": "packages/i18n"
+  },
+  "keywords": [
+    "hazeljs",
+    "i18n",
+    "internationalization",
+    "localization",
+    "translation"
+  ],
+  "author": "Muhammad Arslan <muhammad.arslan@hazeljs.com>",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/hazeljs/hazel-js/issues"
+  },
+  "homepage": "https://hazeljs.com",
+  "peerDependencies": {
+    "@hazeljs/core": ">=0.2.0-beta.0"
+  },
+  "gitHead": "cbc5ee2c12ced28fd0576faf13c5f078c1e8421e"
+}