canopy-i18n 0.0.4 → 0.1.0

package/README.md

@@ -22,18 +22,18 @@ yarn add canopy-i18n
 ## Quick start
 
 ```ts
-import { createMessageBuilder, applyLocaleDeep } from 'canopy-i18n';
+import { createI18n, applyLocale } from 'canopy-i18n';
 
 // 1) Declare allowed locales and fallback
-const builder = createMessageBuilder(['ja', 'en'] as const, 'ja');
+const defineMessage = createI18n(['ja', 'en'] as const, 'ja');
 
 // 2) Define messages
-const title = builder({
+const title = defineMessage({
   ja: 'タイトルテスト',
   en: 'Title Test',
 });
 
-const msg = builder<{ name: string; age: number }>({
+const msg = defineMessage<{ name: string; age: number }>({
   ja: c => `こんにちは、${c.name}さん。あなたは${c.age}歳です。`,
   en: c => `Hello, ${c.name}. You are ${c.age} years old.`,
 });
@@ -42,12 +42,12 @@ const msg = builder<{ name: string; age: number }>({
 const data = {
   title,
   nested: {
-    hello: builder({ ja: 'こんにちは', en: 'Hello' }),
+    hello: defineMessage({ ja: 'こんにちは', en: 'Hello' }),
   },
 };
 
 // 4) Apply locale across the tree
-const localized = applyLocaleDeep(data, 'en');
+const localized = applyLocale(data, 'en');
 
 console.log(localized.title.render());       // "Title Test"
 console.log(localized.nested.hello.render()); // "Hello"
@@ -56,15 +56,15 @@ console.log(msg.setLocale('en').render({ name: 'Tanaka', age: 20 }));
 
 ## API
 
-### createMessageBuilder(locales, fallbackLocale)
-Returns a `builder` function to create localized messages.
+### createI18n(locales, fallbackLocale)
+Returns a `defineMessage` function to create localized messages.
 
 - **locales**: `readonly string[]` — Allowed locale keys (e.g. `['ja', 'en'] as const`).
 - **fallbackLocale**: fallback locale when the active locale value is missing. New messages start with this locale active.
 
 Overloads:
-- `builder<Record<L[number], string>>() -> I18nMessage<L, void>`
-- `builder<Record<L[number], Template<C>>>() -> I18nMessage<L, C>`
+- `defineMessage<Record<L[number], string>>() -> I18nMessage<L, void>`
+- `defineMessage<Record<L[number], Template<C>>>() -> I18nMessage<L, C>`
 
 ### I18nMessage<L, C>
 Represents a single localized message.
@@ -79,7 +79,7 @@ Represents a single localized message.
   - `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)
+### applyLocale(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.
@@ -94,8 +94,8 @@ export type Template<C> = string | ((ctx: C) => string);
 
 ```ts
 export { I18nMessage, isI18nMessage } from 'canopy-i18n';
-export { createMessageBuilder } from 'canopy-i18n';
-export { applyLocaleDeep } from 'canopy-i18n';
+export { createI18n } from 'canopy-i18n';
+export { applyLocale } from 'canopy-i18n';
 export type { Template } from 'canopy-i18n';
 export type { LocalizedMessage } from 'canopy-i18n';
 ```
@@ -112,15 +112,15 @@ Import all message exports as a namespace and set the locale across the whole tr
 
 ```ts
 // messages.ts
-import { createMessageBuilder } from 'canopy-i18n';
-const builder = createMessageBuilder(['ja', 'en'] as const, 'ja');
+import { createI18n } from 'canopy-i18n';
+const defineMessage = createI18n(['ja', 'en'] as const, 'ja');
 
-export const title = builder({
+export const title = defineMessage({
   ja: 'タイトルテスト',
   en: 'Title Test',
 });
 
-export const msg = builder<{ name: string; age: number }>({
+export const msg = defineMessage<{ name: string; age: number }>({
   ja: c => `こんにちは、${c.name}さん。あなたは${c.age}歳です。`,
   en: c => `Hello, ${c.name}. You are ${c.age} years old.`,
 });
@@ -129,9 +129,9 @@ export const msg = builder<{ name: string; age: number }>({
 ```ts
 // usage.ts
 import * as messages from './messages';
-import { applyLocaleDeep } from 'canopy-i18n';
+import { applyLocale } from 'canopy-i18n';
 
-const m = applyLocaleDeep(messages, 'en');
+const m = applyLocale(messages, 'en');
 
 console.log(m.title.render());                     // "Title Test"
 console.log(m.msg.render({ name: 'Tanaka', age: 20 }));
@@ -140,21 +140,21 @@ 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');
+// i18n/defineMessage.ts
+import { createI18n } from 'canopy-i18n';
+export const defineMessage = createI18n(['ja', 'en'] as const, 'ja');
 ```
 
 ```ts
 // i18n/messages/common.ts
-import { builder } from '../builder';
-export const hello = builder({ ja: 'こんにちは', en: 'Hello' });
+import { defineMessage } from '../defineMessage';
+export const hello = defineMessage({ ja: 'こんにちは', en: 'Hello' });
 ```
 
 ```ts
 // i18n/messages/home.ts
-import { builder } from '../builder';
-export const title = builder({ ja: 'タイトル', en: 'Title' });
+import { defineMessage } from '../defineMessage';
+export const title = defineMessage({ ja: 'タイトル', en: 'Title' });
 ```
 
 ```ts
@@ -166,12 +166,30 @@ export * as home from './home';
 ```ts
 // usage.ts
 import * as msgs from './i18n/messages';
-import { applyLocaleDeep } from 'canopy-i18n';
+import { applyLocale } from 'canopy-i18n';
 
-const m = applyLocaleDeep(msgs, 'en');
+const m = applyLocale(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.
+Note: Module namespace objects are read-only; `applyLocale` returns a cloned plain object while updating each `I18nMessage` instance's locale in place.
+
+## Example: Next.js App Router
+
+An example Next.js App Router project lives under `examples/next-app`.
+
+- Server-side usage: `/{locale}/server` renders messages using `applyLocale` in a server component
+- Client-side usage: `/{locale}/client` renders messages using hooks (`useLocale`, `useApplyLocale`)
+
+How to run:
+
+```bash
+git clone https://github.com/mohhh-ok/canopy-i18n
+cd canopy-i18n/examples/next-app
+pnpm install
+pnpm dev
+```
+
+Open `http://localhost:3000` and you will be redirected to `/{locale}` based on `Accept-Language`.

package/dist/applyLocale.d.ts

@@ -0,0 +1 @@
+export declare function applyLocale<T extends object>(obj: T, locale: string): T;

package/dist/applyLocale.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyLocale = applyLocale;
+const message_1 = require("./message");
+function applyLocale(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/createI18n.d.ts

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

package/dist/createI18n.js

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyLocaleDeep = exports.createMessageBuilder = exports.isI18nMessage = exports.I18nMessage = void 0;
+exports.isI18nMessage = exports.I18nMessage = exports.createI18n = exports.applyLocale = void 0;
+var applyLocale_1 = require("./applyLocale");
+Object.defineProperty(exports, "applyLocale", { enumerable: true, get: function () { return applyLocale_1.applyLocale; } });
+var createI18n_1 = require("./createI18n");
+Object.defineProperty(exports, "createI18n", { enumerable: true, get: function () { return createI18n_1.createI18n; } });
 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/testData.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasSentMsg = exports.nested = exports.msg = exports.title = void 0;
 const index_1 = require("./index");
-const builder = (0, index_1.createMessageBuilder)(['ja', 'en'], 'ja');
+const builder = (0, index_1.createI18n)(['ja', 'en'], 'ja');
 exports.title = builder({
     ja: 'タイトルテスト',
     en: 'Title Test'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopy-i18n",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "description": "A tiny, type-safe i18n helper",
   "type": "commonjs",
   "main": "dist/index.js",
@@ -23,7 +23,8 @@
   "devDependencies": {
     "@tsconfig/node20": "^20.1.6",
     "@types/node": "^24.3.3",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
   },
   "keywords": [
     "i18n",
@@ -44,6 +45,8 @@
   "scripts": {
     "dev": "tsc --watch",
     "build": "tsc",
-    "check": "tsc -p . --noEmit"
+    "type-check": "tsc -p . --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }