canopy-i18n 0.6.0 → 0.7.0

package/README.md

@@ -9,7 +9,6 @@ A tiny, type-safe i18n library for building localized messages with builder patt
 - **AI-friendly**: Full type safety and single-file colocation give AI assistants complete context for accurate code generation.
 - **Type-safe**: Compile-time safety for locale keys with full TypeScript IntelliSense support.
 - **Flexible templating**: Plain functions support any JavaScript logic, template literals, or formatting library.
-- **Generic return types**: Return strings, React components, objects, or any custom type.
 - **Zero dependencies**: Lightweight with native TypeScript syntax, no custom {{placeholder}} format.
 ## Why Canopy i18n?
 
@@ -45,32 +44,16 @@ console.log(messages.greeting());  // Fully type-safe, autocomplete works
 **With template functions:**
 ```ts
 const messages = createI18n(['en', 'ja'] as const)
-  .addTemplates<{ name: string }>()({
-    welcome: {
-      en: ({ name }) => `Welcome, ${name}!`,
-      ja: ({ name }) => `ようこそ、${name}さん！`
-    }
+  .add({
+    welcome: (ctx: { name: string }) => ({
+      en: `Welcome, ${ctx.name}!`,
+      ja: `ようこそ、${ctx.name}さん！`
+    })
   }).build('en');
 
 console.log(messages.welcome({ name: 'Alice' }));  // "Welcome, Alice!"
 ```
 
-**With custom return types:**
-```ts
-type MenuItem = { label: string; url: string };
-
-const menu = createI18n(['en', 'ja'] as const)
-  .add<MenuItem>({
-    home: {
-      en: { label: 'Home', url: '/en' },
-      ja: { label: 'ホーム', url: '/ja' }
-    }
-  }).build('ja');
-
-console.log(menu.home().label);  // "ホーム"
-console.log(menu.home().url);    // "/ja"
-```
-
 **Benefits:**
 - 🔒 **Type safety**: Typos caught at compile time, full autocomplete support
 - 📁 **Colocation**: All translations in one place, no file jumping
@@ -109,12 +92,10 @@ const builder = baseBuilder
       ja: 'こんにちは',
       en: 'Hello',
     },
-  })
-  .addTemplates<{ name: string; age: number }>()({
-    welcome: {
-      ja: (ctx) => `こんにちは、${ctx.name}さん。あなたは${ctx.age}歳です。`,
-      en: (ctx) => `Hello, ${ctx.name}. You are ${ctx.age} years old.`,
-    },
+    welcome: (ctx: { name: string; age: number }) => ({
+      ja: `こんにちは、${ctx.name}さん。あなたは${ctx.age}歳です。`,
+      en: `Hello, ${ctx.name}. You are ${ctx.age} years old.`,
+    }),
   });
 
 // 3) Reuse the builder to create messages for different locales
@@ -147,85 +128,53 @@ const builder = createI18n(['ja', 'en', 'fr'] as const);
 ### `ChainBuilder`
 A builder class for creating multiple localized messages with method chaining.
 
-#### `.add<ReturnType = string, K extends string = string>(entries)`
-Adds multiple messages at once. By default, returns `string`, but you can specify a custom return type.
+#### `.add(entries)`
+Adds multiple messages at once. Each entry can be a static locale record or a template function.
 
-- **ReturnType**: (optional) Type parameter for the return value (defaults to `string`)
-- **K**: (optional) Type parameter for the keys of the entries record (defaults to `string`)
-- **entries**: `Record<K, Record<Locale, ReturnType>>`
+- **entries**: `Record<K, Record<Locale, string> | ((ctx: C) => Record<Locale, string>)>`
 - Returns: `ChainBuilder` with added messages
 
 ```ts
-// String messages (default)
+// Static messages
 const builder = createI18n(['ja', 'en'] as const)
   .add({
     title: { ja: 'タイトル', en: 'Title' },
     greeting: { ja: 'こんにちは', en: 'Hello' },
   });
 
-// Custom return type (e.g., React components)
-const messages = createI18n(['ja', 'en'] as const)
-  .add<JSX.Element>({
-    badge: {
-      ja: <span style={{ background: '#ff4444', color: 'white', padding: '2px 6px', borderRadius: '2px' }}>🔴 新着</span>,
-      en: <span style={{ background: '#4caf50', color: 'white', padding: '4px 12px', borderRadius: '16px' }}>✨ NEW</span>,
-    },
-  });
-
-// Custom return type (objects)
-type MenuItem = {
-  label: string;
-  url: string;
-  icon: string;
-};
-
-const menu = createI18n(['ja', 'en'] as const)
-  .add<MenuItem>({
-    home: {
-      ja: { label: 'ホーム', url: '/ja', icon: '🏠' },
-      en: { label: 'Home', url: '/en', icon: '🏡' },
-    },
+// Template functions
+const builder2 = createI18n(['ja', 'en'] as const)
+  .add({
+    greet: (ctx: { name: string; age: number }) => ({
+      ja: `こんにちは、${ctx.name}さん。${ctx.age}歳ですね。`,
+      en: `Hello, ${ctx.name}. You are ${ctx.age}.`,
+    }),
+    farewell: (ctx: { name: string }) => ({
+      ja: `さようなら、${ctx.name}さん。`,
+      en: `Goodbye, ${ctx.name}.`,
+    }),
   });
-```
 
-#### `.addTemplates<Context, ReturnType = string, K extends string = string>()(entries)`
-Adds multiple template function messages at once with a unified context type and custom return type.
-
-Note: This uses a curried API for better type inference. Call `addTemplates<Context, ReturnType, K>()` first, then call the returned function with entries.
-
-- **Context**: Type parameter for the template function context
-- **ReturnType**: (optional) Type parameter for the return value (defaults to `string`)
-- **K**: (optional) Type parameter for the keys of the entries record (defaults to `string`)
-- **entries**: `Record<K, Record<Locale, (ctx: Context) => ReturnType>>`
-- Returns: `ChainBuilder` with added template messages
-
-```ts
-const builder = createI18n(['ja', 'en'] as const)
-  .addTemplates<{ name: string; age: number }>()({
-    greet: {
-      ja: (ctx) => `こんにちは、${ctx.name}さん。${ctx.age}歳ですね。`,
-      en: (ctx) => `Hello, ${ctx.name}. You are ${ctx.age}.`,
-    },
-    farewell: {
-      ja: (ctx) => `さようなら、${ctx.name}さん。`,
-      en: (ctx) => `Goodbye, ${ctx.name}.`,
-    },
+// Mixing static and template messages
+const builder3 = createI18n(['ja', 'en'] as const)
+  .add({
+    title: { ja: 'タイトル', en: 'Title' },
+    greet: (ctx: { name: string }) => ({
+      ja: `こんにちは、${ctx.name}さん`,
+      en: `Hello, ${ctx.name}`,
+    }),
   });
 ```
 
 
 
-#### `.build(locale?)`
+#### `.build(locale)`
 Builds the final messages object.
 
-- **locale**: (optional) `Locale` — If provided, sets this locale on all messages before returning. If omitted, uses the first locale in the locales array as default.
+- **locale**: `Locale` — Sets this locale on all messages before returning.
 - Returns: `Messages` — An object containing all defined messages
 
 ```ts
-// Build with default locale (first in array)
-const defaultMessages = builder.build();
-
-// Build with specific locale
 const englishMessages = builder.build('en');
 const japaneseMessages = builder.build('ja');
 ```
@@ -258,7 +207,7 @@ console.log(localized.nested.special.msg()); // English version
 
 ```ts
 export type Template<C, R = string> = R | ((ctx: C) => R);
-export type LocalizedMessage<Locales, Context, ReturnType = string> = I18nMessage<Locales, Context, ReturnType>;
+export type LocalizedMessage<Locales, Context> = I18nMessage<Locales, Context>;
 ```
 
 ## Exports
@@ -292,11 +241,11 @@ console.log(messages.greeting()); // "Hello"
 
 ```ts
 const messages = createI18n(['ja', 'en'] as const)
-  .addTemplates<{ name: string; age: number }>()({
-    profile: {
-      ja: (ctx) => `名前: ${ctx.name}、年齢: ${ctx.age}歳`,
-      en: (ctx) => `Name: ${ctx.name}, Age: ${ctx.age}`,
-    },
+  .add({
+    profile: (ctx: { name: string; age: number }) => ({
+      ja: `名前: ${ctx.name}、年齢: ${ctx.age}歳`,
+      en: `Name: ${ctx.name}, Age: ${ctx.age}`,
+    }),
   })
   .build('en');
 
@@ -304,18 +253,16 @@ console.log(messages.profile({ name: 'Taro', age: 25 }));
 // "Name: Taro, Age: 25"
 ```
 
-### Mixing String and Template Messages
+### Mixing Static and Template Messages
 
 ```ts
 const messages = createI18n(['ja', 'en'] as const)
   .add({
     title: { ja: 'タイトル', en: 'Title' },
-  })
-  .addTemplates<{ count: number }>()({
-    items: {
-      ja: (ctx) => `${ctx.count}個のアイテム`,
-      en: (ctx) => `${ctx.count} items`,
-    },
+    items: (ctx: { count: number }) => ({
+      ja: `${ctx.count}個のアイテム`,
+      en: `${ctx.count} items`,
+    }),
   })
   .build('ja');
 
@@ -344,11 +291,11 @@ export const common = createI18n(LOCALES).add({
 import { createI18n } from 'canopy-i18n';
 import { LOCALES } from './locales';
 
-export const user = createI18n(LOCALES).addTemplates<{ name: string }>()({
-  welcome: {
-    ja: (ctx) => `ようこそ、${ctx.name}さん`,
-    en: (ctx) => `Welcome, ${ctx.name}`,
-  },
+export const user = createI18n(LOCALES).add({
+  welcome: (ctx: { name: string }) => ({
+    ja: `ようこそ、${ctx.name}さん`,
+    en: `Welcome, ${ctx.name}`,
+  }),
 });
 
 // i18n/index.ts

package/dist/bindLocale.d.ts

@@ -1,8 +1,8 @@
 import { ChainBuilder } from "./chainBuilder.js";
 import { I18nMessage, type LocalizedMessage } from "./message.js";
 export declare function isChainBuilder(x: unknown): x is ChainBuilder<any, any>;
-type DeepUnwrapChainBuilders<T> = T extends I18nMessage<infer Ls, infer C, infer R> ? LocalizedMessage<Ls, C, R> : T extends ChainBuilder<infer Ls, infer Messages> ? {
-    [K in keyof Messages]: Messages[K] extends I18nMessage<Ls, infer C, infer R> ? LocalizedMessage<Ls, C, R> : never;
+type DeepUnwrapChainBuilders<T> = T extends I18nMessage<infer Ls, infer C> ? LocalizedMessage<Ls, C> : T extends ChainBuilder<infer Ls, infer Messages> ? {
+    [K in keyof Messages]: Messages[K] extends I18nMessage<Ls, infer C> ? LocalizedMessage<Ls, C> : never;
 } : T extends readonly any[] ? {
     [K in keyof T]: DeepUnwrapChainBuilders<T[K]>;
 } : T extends object ? {

package/dist/chainBuilder.d.ts

@@ -1,29 +1,20 @@
 import { I18nMessage } from "./message.js";
 import type { LocalizedMessage } from "./message.js";
-export declare class ChainBuilder<const Ls extends readonly string[], Messages extends Record<string, I18nMessage<Ls, any, any>> = {}> {
+export declare class ChainBuilder<const Ls extends readonly string[], Messages extends Record<string, I18nMessage<Ls, any>> = {}> {
     private readonly locales;
     private messages;
     constructor(locales: Ls, messages?: Messages);
     /**
-     * 複数のメッセージを一度に追加
-     * 型パラメータRでカスタム型も指定可能(デフォルトはstring)
+     * 静的メッセージとテンプレート関数を一度に追加
      */
-    add<R = string, K extends string = string, Entries extends Record<K, Record<Ls[number], R>> = Record<K, Record<Ls[number], R>>>(entries: {
+    add<Entries extends Record<string, Record<Ls[number], string> | ((ctx: any) => Record<Ls[number], string>)>>(entries: {
         [Key in keyof Entries]: Key extends keyof Messages ? never : Entries[Key];
     }): ChainBuilder<Ls, Messages & {
-        [Key in keyof Entries]: I18nMessage<Ls, void, R>;
-    }>;
-    /**
-     * 関数指定版: 複数のテンプレート関数を一度に追加(型は統一)
-     */
-    addTemplates<C, R = string, K extends string = string>(): <Entries extends Record<K, Record<Ls[number], (ctx: C) => R>>>(entries: {
-        [Key in keyof Entries]: Key extends keyof Messages ? never : Entries[Key];
-    }) => ChainBuilder<Ls, Messages & {
-        [Key in keyof Entries]: I18nMessage<Ls, C, R>;
+        [Key in keyof Entries]: Entries[Key] extends (ctx: infer C) => any ? I18nMessage<Ls, C> : I18nMessage<Ls, void>;
     }>;
     private deepCloneWithLocale;
     build<M = {
-        [K in keyof Messages]: Messages[K] extends I18nMessage<Ls, infer C, infer R> ? LocalizedMessage<Ls, C, R> : never;
-    }>(locale?: Ls[number]): M;
+        [K in keyof Messages]: Messages[K] extends I18nMessage<Ls, infer C> ? LocalizedMessage<Ls, C> : never;
+    }>(locale: Ls[number]): M;
 }
 export declare function createI18n<const Ls extends readonly string[]>(locales: Ls): ChainBuilder<Ls, {}>;

package/dist/chainBuilder.js

@@ -7,29 +7,26 @@ export class ChainBuilder {
         this.messages = (messages ?? {});
     }
     /**
-     * 複数のメッセージを一度に追加
-     * 型パラメータRでカスタム型も指定可能(デフォルトはstring)
+     * 静的メッセージとテンプレート関数を一度に追加
      */
     add(entries) {
         const newMessages = { ...this.messages };
-        for (const [key, data] of Object.entries(entries)) {
-            const msg = new I18nMessage(this.locales, this.locales[0]).setData(data);
-            newMessages[key] = msg;
-        }
-        return new ChainBuilder(this.locales, newMessages);
-    }
-    /**
-     * 関数指定版: 複数のテンプレート関数を一度に追加(型は統一)
-     */
-    addTemplates() {
-        return (entries) => {
-            const newMessages = { ...this.messages };
-            for (const [key, data] of Object.entries(entries)) {
-                const msg = new I18nMessage(this.locales, this.locales[0]).setData(data);
+        for (const [key, value] of Object.entries(entries)) {
+            if (typeof value === "function") {
+                const fn = value;
+                const localeData = {};
+                for (const locale of this.locales) {
+                    localeData[locale] = (ctx) => fn(ctx)[locale];
+                }
+                const msg = new I18nMessage(this.locales, this.locales[0]).setData(localeData);
                 newMessages[key] = msg;
             }
-            return new ChainBuilder(this.locales, newMessages);
-        };
+            else {
+                const msg = new I18nMessage(this.locales, this.locales[0]).setData(value);
+                newMessages[key] = msg;
+            }
+        }
+        return new ChainBuilder(this.locales, newMessages);
     }
     deepCloneWithLocale(obj, locale) {
         if (isI18nMessage(obj)) {
@@ -51,9 +48,7 @@ export class ChainBuilder {
         return obj;
     }
     build(locale) {
-        const clonedMessages = locale !== undefined
-            ? this.deepCloneWithLocale(this.messages, locale)
-            : this.messages;
+        const clonedMessages = this.deepCloneWithLocale(this.messages, locale);
         const result = {};
         for (const [key, msg] of Object.entries(clonedMessages)) {
             if (isI18nMessage(msg)) {

package/dist/chainBuilder.test.d.ts

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

package/dist/chainBuilder.test.js

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+import { bindLocale } from "./bindLocale.js";
+import { createI18n } from "./chainBuilder.js";
+const LOCALES = ["ja", "en"];
+describe("ChainBuilder", () => {
+    it("builds multiple messages with method chaining", () => {
+        const messages = createI18n(LOCALES)
+            .add({
+            title: {
+                ja: "タイトルテスト",
+                en: "Title Test",
+            },
+            "greeting.hello": {
+                ja: "こんにちは",
+                en: "Hello",
+            },
+            "greeting.bye": {
+                ja: "さようなら",
+                en: "Goodbye",
+            },
+        })
+            .build("ja");
+        expect(messages.title()).toBe("タイトルテスト");
+        expect(messages["greeting.hello"]()).toBe("こんにちは");
+        expect(messages["greeting.bye"]()).toBe("さようなら");
+    });
+    it("supports template functions with type inference", () => {
+        const messages = createI18n(LOCALES)
+            .add({
+            welcome: {
+                ja: "ようこそ",
+                en: "Welcome",
+            },
+            greet: (ctx) => ({
+                ja: `こんにちは、${ctx.name}さん。${ctx.age}歳ですね。`,
+                en: `Hello, ${ctx.name}. You are ${ctx.age}.`,
+            }),
+        })
+            .build("ja");
+        expect(messages.welcome()).toBe("ようこそ");
+        expect(messages.greet({ name: "太郎", age: 25 })).toBe("こんにちは、太郎さん。25歳ですね。");
+    });
+    it("supports adding multiple template messages at once", () => {
+        const messages = createI18n(LOCALES)
+            .add({
+            greet: (ctx) => ({
+                ja: `こんにちは、${ctx.name}さん`,
+                en: `Hello, ${ctx.name}`,
+            }),
+            farewell: (ctx) => ({
+                ja: `さようなら、${ctx.name}さん`,
+                en: `Goodbye, ${ctx.name}`,
+            }),
+        })
+            .build("ja");
+        expect(messages.greet({ name: "太郎" })).toBe("こんにちは、太郎さん");
+        expect(messages.farewell({ name: "花子" })).toBe("さようなら、花子さん");
+    });
+    it("works with applyLocale function", () => {
+        const builder = createI18n(LOCALES)
+            .add({
+            title: { ja: "タイトル", en: "Title" },
+            msg: (c) => ({
+                ja: `こんにちは、${c.name}さん`,
+                en: `Hello, ${c.name}`,
+            }),
+        });
+        const localized = bindLocale(builder, "en");
+        expect(localized.title()).toBe("Title");
+        expect(localized.msg({ name: "John" })).toBe("Hello, John");
+    });
+    it("build() with locale parameter applies locale before building", () => {
+        const messages = createI18n(LOCALES)
+            .add({
+            title: { ja: "タイトル", en: "Title" },
+            greeting: { ja: "こんにちは", en: "Hello" },
+            welcome: (ctx) => ({
+                ja: `ようこそ、${ctx.name}さん`,
+                en: `Welcome, ${ctx.name}`,
+            }),
+        })
+            .build("en");
+        expect(messages.title()).toBe("Title");
+        expect(messages.greeting()).toBe("Hello");
+        expect(messages.welcome({ name: "John" })).toBe("Welcome, John");
+    });
+    it("build(locale) does not mutate the builder instance", () => {
+        const builder = createI18n(LOCALES)
+            .add({
+            title: { ja: "タイトル", en: "Title" },
+        });
+        const englishMessages = builder.build("en");
+        const japaneseMessages = builder.build("ja");
+        expect(englishMessages.title()).toBe("Title");
+        expect(japaneseMessages.title()).toBe("タイトル");
+    });
+    it("applyLocale works with ChainBuilder instances", () => {
+        const builders = {
+            builder1: createI18n(LOCALES).add({ title: { ja: "タイトル", en: "Title" } }),
+            builder2: createI18n(LOCALES).add({ greeting: { ja: "こんにちは", en: "Hello" } }),
+        };
+        const buildersApplied = bindLocale(builders, "ja");
+        expect(buildersApplied.builder1.title()).toBe("タイトル");
+        expect(buildersApplied.builder2.greeting()).toBe("こんにちは");
+    });
+    it("applyLocale works deeply with nested ChainBuilder instances", () => {
+        const builders = {
+            builder1: {
+                builder1child: createI18n(LOCALES).add({ title: { ja: "タイトル", en: "Title" } }),
+            },
+            builder2: createI18n(LOCALES).add({ greeting: { ja: "こんにちは", en: "Hello" } }),
+        };
+        const buildersApplied = bindLocale(builders, "ja");
+        expect(buildersApplied.builder1.builder1child.title()).toBe("タイトル");
+        expect(buildersApplied.builder2.greeting()).toBe("こんにちは");
+    });
+    it("applyLocale works with very deep nested structures", () => {
+        const builders = {
+            level1: {
+                level2: {
+                    level3: createI18n(LOCALES).add({ deep: { ja: "深い", en: "Deep" } }),
+                },
+                builder: createI18n(LOCALES).add({ msg: { ja: "メッセージ", en: "Message" } }),
+            },
+        };
+        const buildersApplied = bindLocale(builders, "en");
+        expect(buildersApplied.level1.level2.level3.deep()).toBe("Deep");
+        expect(buildersApplied.level1.builder.msg()).toBe("Message");
+    });
+});

package/dist/message.d.ts

@@ -1,19 +1,19 @@
 import type { Template } from "./types.js";
-export type LocalizedMessage<Ls extends readonly string[], C, R = string> = C extends void ? (() => R) & {
+export type LocalizedMessage<Ls extends readonly string[], C> = C extends void ? (() => string) & {
     __brand: "I18nMessage";
-} : ((ctx: C) => R) & {
+} : ((ctx: C) => string) & {
     __brand: "I18nTemplateMessage";
 };
-export declare function isI18nMessage(x: unknown): x is I18nMessage<any, any, any>;
-export declare class I18nMessage<Ls extends readonly string[], C, R = string> {
+export declare function isI18nMessage(x: unknown): x is I18nMessage<any, any>;
+export declare class I18nMessage<Ls extends readonly string[], C> {
     readonly locales: Ls;
     private _locale;
     private _data;
     constructor(locales: Ls, locale: Ls[number]);
     get locale(): Ls[number];
     setLocale(locale: Ls[number]): this;
-    get data(): Record<Ls[number], Template<C, R>>;
-    setData(data: Record<Ls[number], Template<C, R>>): this;
+    get data(): Record<Ls[number], Template<C>>;
+    setData(data: Record<Ls[number], Template<C>>): this;
     private render;
-    toFunction(): LocalizedMessage<Ls, C, R>;
+    toFunction(): LocalizedMessage<Ls, C>;
 }

package/dist/testtest.js

@@ -1,9 +1,9 @@
 import { createI18n } from "./chainBuilder.js";
 const a = createI18n(["ja", "en"]);
 const b = a
-    .add({ abc: { ja: "abc", en: "abc" } })
-    .addTemplates()({
-    bb: { ja: ({ aa }) => `${aa}aa`, en: ({ aa }) => `${aa}bb` },
+    .add({
+    abc: { ja: "abc", en: "abc" },
+    bb: (ctx) => ({ ja: `${ctx.aa}aa`, en: `${ctx.aa}bb` }),
 });
 const c = b.build("en");
 const e = { ...c.abc, toString: () => "aaa" };
@@ -11,9 +11,9 @@ const d = b.add({
     aaa: { ja: "aaa", en: "aaa" },
     bbb: { ja: "bbb", en: "bbb" },
 });
-const f = b.addTemplates()({
-    aaa: { ja: ({ a }) => `${a}aaa`, en: ({ a }) => `${a}aaa` },
-    bbb: { ja: ({ a }) => `${a}aaa`, en: ({ a }) => `${a}aaa` },
+const f = b.add({
+    aaa: (ctx) => ({ ja: `${ctx.a}aaa`, en: `${ctx.a}aaa` }),
+    bbb: (ctx) => ({ ja: `${ctx.a}aaa`, en: `${ctx.a}aaa` }),
 });
 console.log(c.bb({ aa: "name" }));
 console.log(`${c.bb({ aa: "name" })}`);

package/dist/types.d.ts

@@ -1,2 +1,2 @@
-export type Template<C, R = string> = R | ((ctx: C) => R);
-export declare function isTemplateFunction<C, R = string>(t: Template<C, R>): t is (ctx: C) => R;
+export type Template<C> = string | ((ctx: C) => string);
+export declare function isTemplateFunction<C>(t: Template<C>): t is (ctx: C) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopy-i18n",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The Type-Safe i18n library that your IDE will Love",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,8 @@
   },
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "skills/SKILL.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -29,8 +30,8 @@
     "release": "release-it"
   },
   "devDependencies": {
-    "@tsconfig/node20": "^20.1.8",
-    "@types/node": "^25.0.10",
+    "@tsconfig/node20": "^20.1.9",
+    "@types/node": "^25.3.0",
     "release-it": "^19.2.4",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

package/skills/SKILL.md

@@ -0,0 +1,476 @@
+---
+name: canopy-i18n
+description: Use this skill when writing code that uses the canopy-i18n package — a type-safe, zero-dependency i18n library with a builder pattern API. Covers createI18n, add (static and template), build, bindLocale, React integration, and common gotchas like required `as const`.
+---
+
+# canopy-i18n — AI Code Generation Reference
+
+A type-safe i18n library using the builder pattern. This reference helps AI assistants generate accurate code for this package.
+
+## Package Overview
+
+- **Type-safe**: Compile-time detection of typos in locale keys via TypeScript inference
+- **Builder pattern**: Define translations with method chaining
+- **Zero dependencies**: Native TypeScript only
+- **ESM only**: Requires `"type": "module"` in `package.json`
+- **Node.js 20+**
+
+---
+
+## Installation
+
+```bash
+npm install canopy-i18n
+# or
+pnpm add canopy-i18n
+bun add canopy-i18n
+```
+
+`package.json` must include `"type": "module"`:
+
+```json
+{
+  "type": "module"
+}
+```
+
+---
+
+## Core API
+
+### `createI18n(locales)`
+
+Creates a builder instance. **`as const` is required** for type inference.
+
+```ts
+import { createI18n } from 'canopy-i18n';
+
+// ✅ Correct: use as const
+const builder = createI18n(['en', 'ja'] as const);
+
+// ❌ Wrong: without as const, type becomes string[] and type inference is lost
+const builder = createI18n(['en', 'ja']);
+```
+
+- **Argument**: `readonly string[]` — allowed locale keys
+- **Returns**: `ChainBuilder<Locales, {}>` — a chain builder instance
+
+---
+
+### `.add(entries)`
+
+Adds multiple messages at once. Each entry can be a static locale record or a template function.
+
+```ts
+// Static messages
+const builder = createI18n(['en', 'ja'] as const)
+  .add({
+    title: { en: 'Title', ja: 'タイトル' },
+    greeting: { en: 'Hello', ja: 'こんにちは' },
+  });
+
+// Template functions
+const builder2 = createI18n(['en', 'ja'] as const)
+  .add({
+    greeting: (ctx: { name: string; age: number }) => ({
+      en: `Hello, ${ctx.name}. You are ${ctx.age}.`,
+      ja: `こんにちは、${ctx.name}さん。${ctx.age}歳です。`,
+    }),
+  });
+
+// Mixing static and template messages in a single add()
+const builder3 = createI18n(['en', 'ja'] as const)
+  .add({
+    title: { en: 'Title', ja: 'タイトル' },
+    greeting: (ctx: { name: string }) => ({
+      en: `Hello, ${ctx.name}`,
+      ja: `こんにちは、${ctx.name}さん`,
+    }),
+  });
+```
+
+- **entries**: `Record<K, Record<Locale, string> | ((ctx: C) => Record<Locale, string>)>`
+- **Returns**: new `ChainBuilder` (immutable)
+
+---
+
+### `.build(locale)`
+
+Builds the final messages object.
+
+```ts
+const builder = createI18n(['en', 'ja'] as const)
+  .add({ title: { en: 'Title', ja: 'タイトル' } });
+
+const enMessages = builder.build('en');
+const jaMessages = builder.build('ja');
+
+// All messages are called as functions
+console.log(enMessages.title()); // "Title"
+console.log(jaMessages.title()); // "タイトル"
+```
+
+- **Argument `locale`**: required
+- **Returns**: `{ [key]: () => R }` or `{ [key]: (ctx: C) => R }`
+- **Immutable**: `.build()` does not mutate the builder — you can generate multiple locales from one builder
+
+---
+
+### `bindLocale(obj, locale)`
+
+Recursively traverses an object/array and calls `.build(locale)` on all `ChainBuilder` instances found. Used for the namespace pattern (split files). Since `build()` requires a locale, `bindLocale` provides it at the point of use.
+
+```ts
+import { bindLocale } from 'canopy-i18n';
+
+const data = {
+  common: commonBuilder,
+  nested: {
+    user: userBuilder,
+  },
+};
+
+const messages = bindLocale(data, 'en');
+console.log(messages.common.hello());                    // "Hello"
+console.log(messages.nested.user.welcome({ name: 'John' })); // "Welcome, John"
+```
+
+- **Argument `obj`**: any object/array containing `ChainBuilder` instances
+- **Argument `locale`**: locale string to apply
+- **Returns**: new structure with all builders resolved
+
+---
+
+## Critical Gotchas
+
+### 1. `as const` is required
+
+```ts
+// ✅ Correct
+createI18n(['en', 'ja'] as const)
+
+// ❌ Type error — locale keys become string, inference breaks
+createI18n(['en', 'ja'])
+```
+
+### 2. `.build()` is immutable
+
+```ts
+const builder = createI18n(['en', 'ja'] as const).add({ ... });
+
+// ✅ Multiple locales from one builder
+const enMessages = builder.build('en');
+const jaMessages = builder.build('ja');
+```
+
+### 3. ESM only
+
+```json
+// Required in package.json
+{ "type": "module" }
+```
+
+### 4. All messages must be called as functions
+
+```ts
+const m = builder.build('en');
+
+// ✅ Call as a function
+m.title()
+m.greeting({ name: 'Alice' })
+
+// ❌ Do not access as property — it is a function object, not a string
+m.title
+```
+
+---
+
+## Common Patterns
+
+### Basic String Messages
+
+```ts
+import { createI18n } from 'canopy-i18n';
+
+const messages = createI18n(['en', 'ja'] as const)
+  .add({
+    title: { en: 'Title', ja: 'タイトル' },
+    greeting: { en: 'Hello', ja: 'こんにちは' },
+    farewell: { en: 'Goodbye', ja: 'さようなら' },
+  })
+  .build('en');
+
+console.log(messages.title());    // "Title"
+console.log(messages.greeting()); // "Hello"
+```
+
+### Template Functions (Variable Interpolation)
+
+```ts
+import { createI18n } from 'canopy-i18n';
+
+const messages = createI18n(['en', 'ja'] as const)
+  .add({
+    profile: (ctx: { name: string; age: number }) => ({
+      en: `Name: ${ctx.name}, Age: ${ctx.age}`,
+      ja: `名前: ${ctx.name}、年齢: ${ctx.age}歳`,
+    }),
+  })
+  .build('en');
+
+console.log(messages.profile({ name: 'Taro', age: 25 }));
+// "Name: Taro, Age: 25"
+```
+
+### Mixing Static and Template Messages
+
+```ts
+import { createI18n } from 'canopy-i18n';
+
+const messages = createI18n(['en', 'ja'] as const)
+  .add({
+    title: { en: 'Items', ja: 'アイテム' },
+    count: (ctx: { count: number }) => ({
+      en: `${ctx.count} items`,
+      ja: `${ctx.count}個のアイテム`,
+    }),
+  })
+  .build('en');
+
+console.log(messages.title());             // "Items"
+console.log(messages.count({ count: 5 })); // "5 items"
+```
+
+### Namespace Pattern (Split Files + bindLocale)
+
+```ts
+// i18n/locales.ts
+export const LOCALES = ['en', 'ja'] as const;
+export type Locale = (typeof LOCALES)[number];
+
+// i18n/common.ts
+import { createI18n } from 'canopy-i18n';
+import { LOCALES } from './locales';
+
+export const common = createI18n(LOCALES).add({
+  hello: { en: 'Hello', ja: 'こんにちは' },
+  goodbye: { en: 'Goodbye', ja: 'さようなら' },
+});
+
+// i18n/user.ts
+import { createI18n } from 'canopy-i18n';
+import { LOCALES } from './locales';
+
+export const user = createI18n(LOCALES)
+  .add({
+    welcome: (ctx: { name: string }) => ({
+      en: `Welcome, ${ctx.name}`,
+      ja: `ようこそ、${ctx.name}さん`,
+    }),
+  });
+
+// i18n/index.ts
+export { common } from './common';
+export { user } from './user';
+
+// app.ts
+import { bindLocale } from 'canopy-i18n';
+import * as i18n from './i18n';
+
+const messages = bindLocale(i18n, 'en');
+console.log(messages.common.hello());                    // "Hello"
+console.log(messages.user.welcome({ name: 'John' }));   // "Welcome, John"
+```
+
+### Deep Nested Structures
+
+```ts
+import { createI18n, bindLocale } from 'canopy-i18n';
+
+const structure = {
+  header: createI18n(['en', 'ja'] as const)
+    .add({ title: { en: 'Header', ja: 'ヘッダー' } }),
+  content: {
+    main: createI18n(['en', 'ja'] as const)
+      .add({ body: { en: 'Body', ja: '本文' } }),
+    sidebar: createI18n(['en', 'ja'] as const)
+      .add({ widget: { en: 'Widget', ja: 'ウィジェット' } }),
+  },
+};
+
+const localized = bindLocale(structure, 'en');
+console.log(localized.header.title());           // "Header"
+console.log(localized.content.main.body());      // "Body"
+console.log(localized.content.sidebar.widget()); // "Widget"
+```
+
+---
+
+## React Integration
+
+### Locale Context
+
+```tsx
+// LocaleContext.tsx
+import { bindLocale } from 'canopy-i18n';
+import { createContext, useContext, useState } from 'react';
+
+type Locale = 'en' | 'ja';
+
+type ContextType = {
+  locale: Locale;
+  setLocale: (locale: Locale) => void;
+};
+
+const LocaleContext = createContext<ContextType | undefined>(undefined);
+
+export function LocaleProvider({ children }: { children: React.ReactNode }) {
+  const [locale, setLocale] = useState<Locale>('en');
+  return (
+    <LocaleContext.Provider value={{ locale, setLocale }}>
+      {children}
+    </LocaleContext.Provider>
+  );
+}
+
+export function useLocale() {
+  const ctx = useContext(LocaleContext);
+  if (!ctx) throw new Error('useLocale must be used within a LocaleProvider');
+  return ctx;
+}
+
+// Reactively applies bindLocale based on current locale
+export function useBindLocale<T extends object>(msgsDef: T) {
+  const { locale } = useLocale();
+  return bindLocale(msgsDef, locale);
+}
+```
+
+### Usage in Components
+
+```tsx
+// i18n.ts — export ChainBuilders (not yet built)
+import { createI18n } from 'canopy-i18n';
+
+const LOCALES = ['en', 'ja'] as const;
+export const defineMessage = () => createI18n(LOCALES);
+
+export const appI18n = defineMessage()
+  .add({
+    title: { en: 'My App', ja: 'マイアプリ' },
+    description: { en: 'Welcome!', ja: 'ようこそ！' },
+    greeting: (ctx: { name: string }) => ({
+      en: `Hello, ${ctx.name}!`,
+      ja: `こんにちは、${ctx.name}さん！`,
+    }),
+  });
+
+// App.tsx — apply locale with useBindLocale
+import { useBindLocale } from './LocaleContext';
+import { appI18n } from './i18n';
+
+export default function App() {
+  const m = useBindLocale(appI18n);
+
+  return (
+    <div>
+      <h1>{m.title()}</h1>
+      <p>{m.description()}</p>
+      <p>{m.greeting({ name: 'Taro' })}</p>
+    </div>
+  );
+}
+```
+
+### Component-Local i18n (Colocation)
+
+```tsx
+// ProfileCard.tsx — define and use i18n in the same file
+import { createI18n } from 'canopy-i18n';
+import type { JSX } from 'react';
+import { useBindLocale } from './LocaleContext';
+
+const profileI18n = createI18n(['en', 'ja'] as const)
+  .add({
+    title: { en: 'User Profile', ja: 'ユーザープロフィール' },
+    editButton: { en: 'Edit Profile', ja: 'プロフィール編集' },
+    greeting: (ctx: { name: string }) => ({
+      en: `Welcome, ${ctx.name}!`,
+      ja: `ようこそ、${ctx.name}さん！`,
+    }),
+  });
+
+export function ProfileCard({ name }: { name: string }) {
+  const m = useBindLocale(profileI18n);
+
+  return (
+    <div>
+      <h2>{m.title()}</h2>
+      <p>{m.greeting({ name })}</p>
+      <button>{m.editButton()}</button>
+    </div>
+  );
+}
+```
+
+### Language Switcher Component
+
+```tsx
+// LanguageSwitcher.tsx
+import { useLocale } from './LocaleContext';
+
+export function LanguageSwitcher() {
+  const { locale, setLocale } = useLocale();
+
+  return (
+    <div>
+      <button onClick={() => setLocale('en')} disabled={locale === 'en'}>EN</button>
+      <button onClick={() => setLocale('ja')} disabled={locale === 'ja'}>JA</button>
+    </div>
+  );
+}
+```
+
+---
+
+## Exports Reference
+
+```ts
+// Functions & Classes
+export { createI18n } from 'canopy-i18n';      // create a builder
+export { ChainBuilder } from 'canopy-i18n';    // builder class
+export { I18nMessage } from 'canopy-i18n';     // message class
+export { isI18nMessage } from 'canopy-i18n';   // type guard
+export { bindLocale } from 'canopy-i18n';      // apply locale to nested structure
+export { isChainBuilder } from 'canopy-i18n';  // type guard
+
+// Types
+export type { Template } from 'canopy-i18n';         // R | ((ctx: C) => R)
+export type { LocalizedMessage } from 'canopy-i18n'; // built message function type
+```
+
+### Type Details
+
+```ts
+// Template<C, R>: a static value or a function that receives context
+type Template<C, R = string> = R | ((ctx: C) => R);
+
+// LocalizedMessage<Ls, C, R>: the function type after build()
+// - when C is void: () => R
+// - when C is present: (ctx: C) => R
+type LocalizedMessage<Ls, C, R = string> =
+  C extends void
+    ? (() => R) & { __brand: "I18nMessage" }
+    : ((ctx: C) => R) & { __brand: "I18nTemplateMessage" };
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| `createI18n(['en', 'ja'])` | `createI18n(['en', 'ja'] as const)` |
+| `messages.title` | `messages.title()` (call as function) |
+| CommonJS `require()` | Use ESM `import` |
+| Typo in locale key | TypeScript catches it at compile time |