canopy-i18n 0.0.1

package/README.md

@@ -0,0 +1,178 @@
+## canopy-i18n
+
+A tiny, type-safe i18n helper for building localized messages and applying a locale across nested data structures.
+
+### Features
+- **Type-safe locales**: Compile-time safety for allowed locale keys.
+- **Per-message fallback**: Each message knows its default and fallback locale.
+- **Template or string**: Use plain strings or `(ctx) => string` templates.
+- **Flexible templating**: Since templates are plain functions, you can freely use JavaScript template literals, conditionals, helpers, or any formatting library. This library does not provide a tagged template literal API.
+- **Deep locale application**: Switch locale across entire object/array trees.
+
+## Installation
+
+```bash
+npm install canopy-i18n
+# or
+pnpm add canopy-i18n
+# or
+yarn add canopy-i18n
+```
+
+## Quick start
+
+```ts
+import { createMessageBuilder, applyLocaleDeep } from 'canopy-i18n';
+
+// 1) Declare allowed locales and defaults
+const builder = createMessageBuilder(['ja', 'en'] as const, 'ja', 'ja');
+
+// 2) Define messages
+const title = builder({
+  ja: 'タイトルテスト',
+  en: 'Title Test',
+});
+
+const msg = builder<{ name: string; age: number }>({
+  ja: c => `こんにちは、${c.name}さん。あなたは${c.age}歳です。`,
+  en: c => `Hello, ${c.name}. You are ${c.age} years old.`,
+});
+
+// 3) Compose nested data structures
+const data = {
+  title,
+  nested: {
+    hello: builder({ ja: 'こんにちは', en: 'Hello' }),
+  },
+};
+
+// 4) Apply locale across the tree
+const localized = applyLocaleDeep(data, 'en');
+
+console.log(localized.title.render());       // "Title Test"
+console.log(localized.nested.hello.render()); // "Hello"
+console.log(msg.setLocale('en').render({ name: 'Tanaka', age: 20 }));
+```
+
+## API
+
+### createMessageBuilder(locales, locale, fallbackLocale)
+Returns a `builder` function to create localized messages.
+
+- **locales**: `readonly string[]` — Allowed locale keys (e.g. `['ja', 'en'] as const`).
+- **locale**: default active locale for new messages.
+- **fallbackLocale**: fallback locale when the active locale value is missing.
+
+Overloads:
+- `builder<Record<L[number], string>>() -> I18nMessage<L, void>`
+- `builder<Record<L[number], Template<C>>>() -> I18nMessage<L, C>`
+
+### I18nMessage<L, C>
+Represents a single localized message.
+
+- **properties**
+  - `locales: L`
+  - `locale: L[number]` (getter)
+  - `fallbackLocale: L[number]` (getter)
+  - `data: Record<L[number], Template<C>>`
+- **methods**
+  - `setLocale(locale: L[number]): this`
+  - `setFallbackLocale(locale: L[number]): this`
+  - `render(ctx?: C): string` — If the value for the active locale is a function, it’s invoked with `ctx`; otherwise the string is returned. Falls back to `fallbackLocale` if needed.
+
+### applyLocaleDeep(obj, locale)
+Recursively traverses arrays/objects and sets the given `locale` on all `I18nMessage` instances encountered.
+
+- Returns a new container (arrays/objects are cloned), but reuses the same message instances after updating their locale.
+
+## Types
+
+```ts
+export type Template<C> = string | ((ctx: C) => string);
+```
+
+## Exports
+
+```ts
+export { I18nMessage, isI18nMessage } from 'canopy-i18n';
+export { createMessageBuilder } from 'canopy-i18n';
+export { applyLocaleDeep } from 'canopy-i18n';
+export type { Template } from 'canopy-i18n';
+export type { LocalizedMessage } from 'canopy-i18n';
+```
+
+## Notes
+- CommonJS build (`main: dist/index.js`) with TypeScript type declarations (`types: dist/index.d.ts`).
+- Works in Node or bundlers; recommended usage is TypeScript/ESM import via your build tool.
+- License: MIT.
+ - Not a tagged template library: you write plain functions (examples use JS template literals inside those functions).
+
+### Split files example (namespace import)
+
+Import all message exports as a namespace and set the locale across the whole tree.
+
+```ts
+// messages.ts
+import { createMessageBuilder } from 'canopy-i18n';
+const builder = createMessageBuilder(['ja', 'en'] as const, 'ja', 'ja');
+
+export const title = builder({
+  ja: 'タイトルテスト',
+  en: 'Title Test',
+});
+
+export const msg = builder<{ name: string; age: number }>({
+  ja: c => `こんにちは、${c.name}さん。あなたは${c.age}歳です。`,
+  en: c => `Hello, ${c.name}. You are ${c.age} years old.`,
+});
+```
+
+```ts
+// usage.ts
+import * as messages from './messages';
+import { applyLocaleDeep } from 'canopy-i18n';
+
+const m = applyLocaleDeep(messages, 'en');
+
+console.log(m.title.render());                     // "Title Test"
+console.log(m.msg.render({ name: 'Tanaka', age: 20 }));
+```
+
+#### Multi-file structure
+
+```ts
+// i18n/builder.ts
+import { createMessageBuilder } from 'canopy-i18n';
+export const builder = createMessageBuilder(['ja', 'en'] as const, 'ja', 'ja');
+```
+
+```ts
+// i18n/messages/common.ts
+import { builder } from '../builder';
+export const hello = builder({ ja: 'こんにちは', en: 'Hello' });
+```
+
+```ts
+// i18n/messages/home.ts
+import { builder } from '../builder';
+export const title = builder({ ja: 'タイトル', en: 'Title' });
+```
+
+```ts
+// i18n/messages/index.ts
+export * as common from './common';
+export * as home from './home';
+```
+
+```ts
+// usage.ts
+import * as msgs from './i18n/messages';
+import { applyLocaleDeep } from 'canopy-i18n';
+
+const m = applyLocaleDeep(msgs, 'en');
+
+console.log(m.common.hello.render()); // "Hello"
+console.log(m.home.title.render());   // "Title"
+```
+
+Note: Module namespace objects are read-only; `applyLocaleDeep` returns a cloned plain object while updating each `I18nMessage` instance's locale in place.

package/dist/applyLocaleDeep.d.ts

@@ -0,0 +1,2 @@
+export declare function applyLocaleDeep<T extends Record<string, unknown>>(obj: T, locale: string): T;
+export declare function applyLocaleDeep<T extends unknown[]>(obj: T, locale: string): T;

package/dist/applyLocaleDeep.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyLocaleDeep = applyLocaleDeep;
+const message_1 = require("./message");
+function applyLocaleDeep(obj, locale) {
+    function visit(v) {
+        if ((0, message_1.isI18nMessage)(v)) {
+            v.setLocale(locale);
+            return v;
+        }
+        if (Array.isArray(v)) {
+            return v.map(visit);
+        }
+        if (v && typeof v === 'object') {
+            const out = {};
+            for (const k of Object.keys(v)) {
+                out[k] = visit(v[k]);
+            }
+            return out;
+        }
+        return v;
+    }
+    return visit(obj);
+}

package/dist/builder.d.ts

@@ -0,0 +1,6 @@
+import { Template } from "./types";
+import { LocalizedMessage } from "./message";
+export declare function createMessageBuilder<const Ls extends readonly string[]>(locales: Ls, locale: Ls[number], fallbackLocale: Ls[number]): {
+    <C>(data: Record<Ls[number], Template<C>>): LocalizedMessage<Ls, C>;
+    (data: Record<Ls[number], string>): LocalizedMessage<Ls, void>;
+};

package/dist/builder.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMessageBuilder = createMessageBuilder;
+const message_1 = require("./message");
+function createMessageBuilder(locales, locale, fallbackLocale) {
+    function builder(data) {
+        return new message_1.I18nMessage(locales, locale, fallbackLocale, data);
+    }
+    return builder;
+}

package/dist/createBuilder.d.ts

@@ -0,0 +1,29 @@
+export type Template<C> = string | ((ctx: C) => string);
+export declare class Li18nMessage<Ls extends readonly string[], C> {
+    readonly locales: Ls;
+    private _locale;
+    private _fallbackLocale;
+    readonly data: Record<Ls[number], Template<C>>;
+    constructor(locales: Ls, _locale: Ls[number], _fallbackLocale: Ls[number], data: Record<Ls[number], Template<C>>);
+    get locale(): Ls[number];
+    get fallbackLocale(): Ls[number];
+    setLocale(locale: Ls[number]): this;
+    setFallbackLocale(locale: Ls[number]): this;
+    render(this: Li18nMessage<Ls, void>): string;
+    render(ctx: C): string;
+}
+export type LocalizedMessage<Ls extends readonly string[], C> = Li18nMessage<Ls, C>;
+export declare function createMessageBuilder<const Ls extends readonly string[]>(locales: Ls, locale: Ls[number], fallbackLocale: Ls[number]): {
+    <C>(data: Record<Ls[number], Template<C>>): LocalizedMessage<Ls, C>;
+    (data: Record<Ls[number], string>): LocalizedMessage<Ls, void>;
+};
+/**
+ * Recursively apply locale for any Li18nMessage instances found in the given value.
+ * Always deep; does not change fallback locale (keeps builder defaults).
+ *
+ * Example:
+ *   import * as trs from './testData';
+ *   applyLocaleDeep(trs, 'en');
+ */
+export declare function applyLocaleDeep<T extends Record<string, unknown>>(obj: T, locale: string): T;
+export declare function applyLocaleDeep<T extends unknown[]>(obj: T, locale: string): T;

package/dist/createBuilder.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Li18nMessage = void 0;
+exports.createMessageBuilder = createMessageBuilder;
+exports.applyLocaleDeep = applyLocaleDeep;
+function isTemplateFunction(t) {
+    return typeof t === 'function';
+}
+class Li18nMessage {
+    locales;
+    _locale;
+    _fallbackLocale;
+    data;
+    constructor(locales, _locale, _fallbackLocale, data) {
+        this.locales = locales;
+        this._locale = _locale;
+        this._fallbackLocale = _fallbackLocale;
+        this.data = data;
+    }
+    get locale() {
+        return this._locale;
+    }
+    get fallbackLocale() {
+        return this._fallbackLocale;
+    }
+    setLocale(locale) {
+        this._locale = locale;
+        return this;
+    }
+    setFallbackLocale(locale) {
+        this._fallbackLocale = locale;
+        return this;
+    }
+    render(ctx) {
+        const v = this.data[this._locale] ?? this.data[this._fallbackLocale];
+        return isTemplateFunction(v) ? v(ctx) : v;
+    }
+}
+exports.Li18nMessage = Li18nMessage;
+function createMessageBuilder(locales, locale, fallbackLocale) {
+    function builder(data) {
+        return new Li18nMessage(locales, locale, fallbackLocale, data);
+    }
+    return builder;
+}
+function isLi18nMessage(x) {
+    return x instanceof Li18nMessage;
+}
+function applyLocaleDeep(obj, locale) {
+    function visit(v) {
+        if (isLi18nMessage(v)) {
+            v.setLocale(locale);
+            return v;
+        }
+        if (Array.isArray(v)) {
+            return v.map(visit);
+        }
+        // Traverse any non-null object (including module namespace objects),
+        // but avoid special handling already covered above.
+        if (v && typeof v === 'object') {
+            const out = {};
+            for (const k of Object.keys(v)) {
+                out[k] = visit(v[k]);
+            }
+            return out;
+        }
+        return v;
+    }
+    return visit(obj);
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { Template } from './types';
+export { I18nMessage, isI18nMessage } from './message';
+export type { LocalizedMessage } from './message';
+export { createMessageBuilder } from './builder';
+export { applyLocaleDeep } from './applyLocaleDeep';

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyLocaleDeep = exports.createMessageBuilder = exports.isI18nMessage = exports.I18nMessage = void 0;
+var message_1 = require("./message");
+Object.defineProperty(exports, "I18nMessage", { enumerable: true, get: function () { return message_1.I18nMessage; } });
+Object.defineProperty(exports, "isI18nMessage", { enumerable: true, get: function () { return message_1.isI18nMessage; } });
+var builder_1 = require("./builder");
+Object.defineProperty(exports, "createMessageBuilder", { enumerable: true, get: function () { return builder_1.createMessageBuilder; } });
+var applyLocaleDeep_1 = require("./applyLocaleDeep");
+Object.defineProperty(exports, "applyLocaleDeep", { enumerable: true, get: function () { return applyLocaleDeep_1.applyLocaleDeep; } });

package/dist/message.d.ts

@@ -0,0 +1,16 @@
+import { Template } from "./types";
+export declare class I18nMessage<Ls extends readonly string[], C> {
+    readonly locales: Ls;
+    private _locale;
+    private _fallbackLocale;
+    readonly data: Record<Ls[number], Template<C>>;
+    constructor(locales: Ls, _locale: Ls[number], _fallbackLocale: Ls[number], data: Record<Ls[number], Template<C>>);
+    get locale(): Ls[number];
+    get fallbackLocale(): Ls[number];
+    setLocale(locale: Ls[number]): this;
+    setFallbackLocale(locale: Ls[number]): this;
+    render(this: I18nMessage<Ls, void>): string;
+    render(ctx: C): string;
+}
+export type LocalizedMessage<Ls extends readonly string[], C> = I18nMessage<Ls, C>;
+export declare function isI18nMessage(x: unknown): x is I18nMessage<any, any>;

package/dist/message.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18nMessage = void 0;
+exports.isI18nMessage = isI18nMessage;
+function isTemplateFunction(t) {
+    return typeof t === 'function';
+}
+class I18nMessage {
+    locales;
+    _locale;
+    _fallbackLocale;
+    data;
+    constructor(locales, _locale, _fallbackLocale, data) {
+        this.locales = locales;
+        this._locale = _locale;
+        this._fallbackLocale = _fallbackLocale;
+        this.data = data;
+    }
+    get locale() {
+        return this._locale;
+    }
+    get fallbackLocale() {
+        return this._fallbackLocale;
+    }
+    setLocale(locale) {
+        this._locale = locale;
+        return this;
+    }
+    setFallbackLocale(locale) {
+        this._fallbackLocale = locale;
+        return this;
+    }
+    render(ctx) {
+        const v = this.data[this._locale] ?? this.data[this._fallbackLocale];
+        return isTemplateFunction(v) ? v(ctx) : v;
+    }
+}
+exports.I18nMessage = I18nMessage;
+function isI18nMessage(x) {
+    return x instanceof I18nMessage;
+}

package/dist/test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+const trs = require("./testData");
+for (const locale of ['ja', 'en']) {
+    const { msg, title, nested } = (0, index_1.applyLocaleDeep)(trs, locale);
+    console.log(msg.render({ name: '田中', age: 20 }));
+    console.log(title.render());
+    console.log(nested.hello.render());
+}

package/dist/testData.d.ts

@@ -0,0 +1,9 @@
+export declare const title: import("./message").LocalizedMessage<readonly ["ja", "en"], unknown>;
+export declare const msg: import("./message").LocalizedMessage<readonly ["ja", "en"], {
+    name: string;
+    age: number;
+}>;
+export declare const nested: {
+    hello: import("./message").LocalizedMessage<readonly ["ja", "en"], unknown>;
+    world: import("./message").LocalizedMessage<readonly ["ja", "en"], unknown>;
+};

package/dist/testData.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nested = exports.msg = exports.title = void 0;
+const index_1 = require("./index");
+const builder = (0, index_1.createMessageBuilder)(['ja', 'en'], 'ja', 'ja');
+exports.title = builder({
+    ja: 'タイトルテスト',
+    en: 'Title Test'
+});
+exports.msg = builder({
+    ja: c => `こんにちは、${c.name}さん、あなたは${c.age}歳です。来年は${c.age + 1}歳です。`,
+    en: c => `Hello, ${c.name}. You are ${c.age} years old. Next year you will be ${c.age + 1} years old.`
+});
+exports.nested = {
+    hello: builder({
+        ja: 'こんにちは',
+        en: 'Hello'
+    }),
+    world: builder({
+        ja: '世界',
+        en: 'World'
+    })
+};

package/dist/types.d.ts

@@ -0,0 +1 @@
+export type Template<C> = string | ((ctx: C) => string);

package/dist/types.js

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

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "canopy-i18n",
+  "version": "0.0.1",
+  "description": "A tiny, type-safe i18n helper",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@tsconfig/node20": "^20.1.6",
+    "@types/node": "^24.3.3",
+    "typescript": "^5.9.2"
+  },
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "localization",
+    "l10n",
+    "messages",
+    "template"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MOhhh-ok/canopy-i18n"
+  },
+  "scripts": {
+    "dev": "tsc --watch",
+    "build": "tsc",
+    "check": "tsc -p . --noEmit"
+  }
+}