canopy-i18n 0.6.1 → 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.1",
+  "version": "0.7.0",
   "description": "The Type-Safe i18n library that your IDE will Love",
   "type": "module",
   "main": "dist/index.js",

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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, addTemplates (curried), build, bindLocale, React integration, and common gotchas like required `as const` and the two-step curried call syntax.
+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
@@ -57,70 +57,44 @@ const builder = createI18n(['en', 'ja']);
 
 ---
 
-### `.add<R, K>(entries)`
+### `.add(entries)`
 
-Adds multiple static messages (string or custom type).
+Adds multiple messages at once. Each entry can be a static locale record or a template function.
 
 ```ts
-// Default (string type)
+// Static messages
 const builder = createI18n(['en', 'ja'] as const)
   .add({
     title: { en: 'Title', ja: 'タイトル' },
     greeting: { en: 'Hello', ja: 'こんにちは' },
   });
 
-// Custom return type (object)
-type MenuItem = { label: string; url: string };
-
-const menu = createI18n(['en', 'ja'] as const)
-  .add<MenuItem>({
-    home: {
-      en: { label: 'Home', url: '/en' },
-      ja: { label: 'Home', url: '/ja' },
-    },
-  });
-```
-
-- **Type param `R`**: return value type (default: `string`)
-- **Type param `K`**: key type for entries (usually omitted)
-- **entries**: `Record<K, Record<Locale, R>>`
-- **Returns**: new `ChainBuilder` (immutable)
-
----
-
-### `.addTemplates<C, R, K>()(entries)`
-
-**Curried API — two-step call required.** Adds template functions that receive a context object of type `C`.
-
-```ts
-// ⚠️ Curried: two-step call ()() is mandatory
-const builder = createI18n(['en', 'ja'] as const)
-  .addTemplates<{ name: string; age: number }>()({  // note: ()() two steps
-    greeting: {
-      en: (ctx) => `Hello, ${ctx.name}. You are ${ctx.age}.`,
-      ja: (ctx) => `こんにちは、${ctx.name}さん。${ctx.age}歳です。`,
-    },
+// 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}歳です。`,
+    }),
   });
 
-// Custom return type (JSX.Element)
-const jsxBuilder = createI18n(['en', 'ja'] as const)
-  .addTemplates<{ name: string }, JSX.Element>()({
-    badge: {
-      en: ({ name }) => <strong>Welcome, {name}!</strong>,
-      ja: ({ name }) => <strong>ようこそ、{name}さん！</strong>,
-    },
+// 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}さん`,
+    }),
   });
 ```
 
-- **Type param `C`**: context object type (**required**)
-- **Type param `R`**: return value type (default: `string`)
-- **Type param `K`**: key type (usually omitted)
-- **entries**: `Record<K, Record<Locale, (ctx: C) => R>>`
+- **entries**: `Record<K, Record<Locale, string> | ((ctx: C) => Record<Locale, string>)>`
 - **Returns**: new `ChainBuilder` (immutable)
 
 ---
 
-### `.build(locale?)`
+### `.build(locale)`
 
 Builds the final messages object.
 
@@ -128,19 +102,15 @@ Builds the final messages object.
 const builder = createI18n(['en', 'ja'] as const)
   .add({ title: { en: 'Title', ja: 'タイトル' } });
 
-// With specific locale
 const enMessages = builder.build('en');
 const jaMessages = builder.build('ja');
 
-// Without locale — defaults to first locale in array
-const defaultMessages = builder.build(); // uses 'en'
-
 // All messages are called as functions
 console.log(enMessages.title()); // "Title"
 console.log(jaMessages.title()); // "タイトル"
 ```
 
-- **Argument `locale`**: optional; defaults to first locale in array
+- **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
 
@@ -148,7 +118,7 @@ console.log(jaMessages.title()); // "タイトル"
 
 ### `bindLocale(obj, locale)`
 
-Recursively traverses an object/array and calls `.build(locale)` on all `ChainBuilder` instances found. Used for the namespace pattern (split files).
+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';
@@ -183,21 +153,7 @@ createI18n(['en', 'ja'] as const)
 createI18n(['en', 'ja'])
 ```
 
-### 2. `addTemplates` is curried — two-step call
-
-```ts
-// ✅ Correct: ()() two steps
-.addTemplates<{ name: string }>()({
-  key: { en: (ctx) => `Hello, ${ctx.name}` }
-})
-
-// ❌ Wrong: one-step call causes type error
-.addTemplates<{ name: string }>({
-  key: { en: (ctx) => `Hello, ${ctx.name}` }
-})
-```
-
-### 3. `.build()` is immutable
+### 2. `.build()` is immutable
 
 ```ts
 const builder = createI18n(['en', 'ja'] as const).add({ ... });
@@ -207,14 +163,14 @@ const enMessages = builder.build('en');
 const jaMessages = builder.build('ja');
 ```
 
-### 4. ESM only
+### 3. ESM only
 
 ```json
 // Required in package.json
 { "type": "module" }
 ```
 
-### 5. All messages must be called as functions
+### 4. All messages must be called as functions
 
 ```ts
 const m = builder.build('en');
@@ -254,11 +210,11 @@ console.log(messages.greeting()); // "Hello"
 import { createI18n } from 'canopy-i18n';
 
 const messages = createI18n(['en', 'ja'] as const)
-  .addTemplates<{ name: string; age: number }>()({
-    profile: {
-      en: (ctx) => `Name: ${ctx.name}, Age: ${ctx.age}`,
-      ja: (ctx) => `名前: ${ctx.name}、年齢: ${ctx.age}歳`,
-    },
+  .add({
+    profile: (ctx: { name: string; age: number }) => ({
+      en: `Name: ${ctx.name}, Age: ${ctx.age}`,
+      ja: `名前: ${ctx.name}、年齢: ${ctx.age}歳`,
+    }),
   })
   .build('en');
 
@@ -274,12 +230,10 @@ import { createI18n } from 'canopy-i18n';
 const messages = createI18n(['en', 'ja'] as const)
   .add({
     title: { en: 'Items', ja: 'アイテム' },
-  })
-  .addTemplates<{ count: number }>()({
-    count: {
-      en: (ctx) => `${ctx.count} items`,
-      ja: (ctx) => `${ctx.count}個のアイテム`,
-    },
+    count: (ctx: { count: number }) => ({
+      en: `${ctx.count} items`,
+      ja: `${ctx.count}個のアイテム`,
+    }),
   })
   .build('en');
 
@@ -287,55 +241,6 @@ console.log(messages.title());             // "Items"
 console.log(messages.count({ count: 5 })); // "5 items"
 ```
 
-### Custom Return Type (Object)
-
-```ts
-import { createI18n } from 'canopy-i18n';
-
-type MenuItem = { label: string; url: string; icon: string };
-
-const menu = createI18n(['en', 'ja'] as const)
-  .add<MenuItem>({
-    home: {
-      en: { label: 'Home', url: '/en', icon: '🏡' },
-      ja: { label: 'ホーム', url: '/ja', icon: '🏠' },
-    },
-    about: {
-      en: { label: 'About', url: '/en/about', icon: 'ℹ️' },
-      ja: { label: '概要', url: '/ja/about', icon: 'ℹ️' },
-    },
-  })
-  .build('en');
-
-console.log(menu.home().label); // "Home"
-console.log(menu.home().url);   // "/en"
-```
-
-### Custom Return Type (JSX)
-
-```tsx
-import { createI18n } from 'canopy-i18n';
-import type { JSX } from 'react';
-
-const messages = createI18n(['en', 'ja'] as const)
-  .add<JSX.Element>({
-    badge: {
-      en: <span style={{ background: '#4caf50', color: 'white' }}>NEW</span>,
-      ja: <span style={{ background: '#ff4444', color: 'white' }}>新着</span>,
-    },
-  })
-  .addTemplates<{ name: string }, JSX.Element>()({
-    greeting: {
-      en: ({ name }) => <strong>Welcome, {name}!</strong>,
-      ja: ({ name }) => <strong>ようこそ、{name}さん！</strong>,
-    },
-  })
-  .build('en');
-
-const badge = messages.badge();
-const greeting = messages.greeting({ name: 'Alice' });
-```
-
 ### Namespace Pattern (Split Files + bindLocale)
 
 ```ts
@@ -357,11 +262,11 @@ import { createI18n } from 'canopy-i18n';
 import { LOCALES } from './locales';
 
 export const user = createI18n(LOCALES)
-  .addTemplates<{ name: string }>()({
-    welcome: {
-      en: (ctx) => `Welcome, ${ctx.name}`,
-      ja: (ctx) => `ようこそ、${ctx.name}さん`,
-    },
+  .add({
+    welcome: (ctx: { name: string }) => ({
+      en: `Welcome, ${ctx.name}`,
+      ja: `ようこそ、${ctx.name}さん`,
+    }),
   });
 
 // i18n/index.ts
@@ -454,12 +359,10 @@ export const appI18n = defineMessage()
   .add({
     title: { en: 'My App', ja: 'マイアプリ' },
     description: { en: 'Welcome!', ja: 'ようこそ！' },
-  })
-  .addTemplates<{ name: string }>()({
-    greeting: {
-      en: (ctx) => `Hello, ${ctx.name}!`,
-      ja: (ctx) => `こんにちは、${ctx.name}さん！`,
-    },
+    greeting: (ctx: { name: string }) => ({
+      en: `Hello, ${ctx.name}!`,
+      ja: `こんにちは、${ctx.name}さん！`,
+    }),
   });
 
 // App.tsx — apply locale with useBindLocale
@@ -491,12 +394,10 @@ const profileI18n = createI18n(['en', 'ja'] as const)
   .add({
     title: { en: 'User Profile', ja: 'ユーザープロフィール' },
     editButton: { en: 'Edit Profile', ja: 'プロフィール編集' },
-  })
-  .addTemplates<{ name: string }, JSX.Element>()({
-    greeting: {
-      en: ({ name }) => <strong>Welcome, {name}!</strong>,
-      ja: ({ name }) => <strong>ようこそ、{name}さん！</strong>,
-    },
+    greeting: (ctx: { name: string }) => ({
+      en: `Welcome, ${ctx.name}!`,
+      ja: `ようこそ、${ctx.name}さん！`,
+    }),
   });
 
 export function ProfileCard({ name }: { name: string }) {
@@ -505,7 +406,7 @@ export function ProfileCard({ name }: { name: string }) {
   return (
     <div>
       <h2>{m.title()}</h2>
-      <div>{m.greeting({ name })}</div>
+      <p>{m.greeting({ name })}</p>
       <button>{m.editButton()}</button>
     </div>
   );
@@ -570,7 +471,6 @@ type LocalizedMessage<Ls, C, R = string> =
 | Mistake | Fix |
 |---------|-----|
 | `createI18n(['en', 'ja'])` | `createI18n(['en', 'ja'] as const)` |
-| `.addTemplates<C>({ ... })` | `.addTemplates<C>()({ ... })` (two-step) |
 | `messages.title` | `messages.title()` (call as function) |
 | CommonJS `require()` | Use ESM `import` |
 | Typo in locale key | TypeScript catches it at compile time |