canopy-i18n 0.4.2 → 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Masaaki Ota
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,6 +2,9 @@
 
 A tiny, type-safe i18n library for building localized messages with builder pattern and applying locales across nested data structures.
 
+![スクリーンショット](https://raw.githubusercontent.com/mohhh-ok/canopy-i18n/main/docs/images/hero.gif)
+
+
 ## Features
 - **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.
@@ -36,7 +39,7 @@ const messages = createI18n(['en', 'ja'] as const).add({
   farewell: { en: 'Goodbye', ja: 'さようなら' }
 }).build('en');
 
-console.log(messages.greeting);  // Fully type-safe, autocomplete works
+console.log(messages.greeting());  // Fully type-safe, autocomplete works
 ```
 
 **With template functions:**
@@ -64,8 +67,8 @@ const menu = createI18n(['en', 'ja'] as const)
     }
   }).build('ja');
 
-console.log(menu.home.label);  // "ホーム"
-console.log(menu.home.url);    // "/ja"
+console.log(menu.home().label);  // "ホーム"
+console.log(menu.home().url);    // "/ja"
 ```
 
 **Benefits:**
@@ -118,15 +121,15 @@ const builder = baseBuilder
 const enMessages = builder.build('en');
 const jaMessages = builder.build('ja');
 
-// 4) Render messages (English)
-console.log(enMessages.title.render());                        // "Title Test"
-console.log(enMessages.greeting.render());                     // "Hello"
-console.log(enMessages.welcome.render({ name: 'Tanaka', age: 20 })); // "Hello, Tanaka. You are 20 years old."
+// 4) Use messages (English)
+console.log(enMessages.title());                        // "Title Test"
+console.log(enMessages.greeting());                     // "Hello"
+console.log(enMessages.welcome({ name: 'Tanaka', age: 20 })); // "Hello, Tanaka. You are 20 years old."
 
-// 5) Render messages (Japanese)
-console.log(jaMessages.title.render());                        // "タイトルテスト"
-console.log(jaMessages.greeting.render());                     // "こんにちは"
-console.log(jaMessages.welcome.render({ name: 'Tanaka', age: 20 })); // "こんにちは、Tanakaさん。あなたは20歳です。"
+// 5) Use messages (Japanese)
+console.log(jaMessages.title());                        // "タイトルテスト"
+console.log(jaMessages.greeting());                     // "こんにちは"
+console.log(jaMessages.welcome({ name: 'Tanaka', age: 20 })); // "こんにちは、Tanakaさん。あなたは20歳です。"
 ```
 
 ## API
@@ -163,8 +166,8 @@ const builder = createI18n(['ja', 'en'] as const)
 const messages = createI18n(['ja', 'en'] as const)
   .add<JSX.Element>({
     badge: {
-      ja: <span style={{ color: 'red' }}>新着</span>,
-      en: <span style={{ color: 'red' }}>NEW</span>,
+      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>,
     },
   });
 
@@ -172,13 +175,14 @@ const messages = createI18n(['ja', 'en'] as const)
 type MenuItem = {
   label: string;
   url: string;
+  icon: string;
 };
 
 const menu = createI18n(['ja', 'en'] as const)
   .add<MenuItem>({
     home: {
-      ja: { label: 'ホーム', url: '/' },
-      en: { label: 'Home', url: '/' },
+      ja: { label: 'ホーム', url: '/ja', icon: '🏠' },
+      en: { label: 'Home', url: '/en', icon: '🏡' },
     },
   });
 ```
@@ -226,55 +230,6 @@ const japaneseMessages = builder.build('ja');
 
 **Note**: `build(locale)` creates a deep clone and does not mutate the builder instance, allowing you to build multiple locale versions from the same builder.
 
-#### `.clone()`
-Creates an independent copy of the current builder with all its messages.
-
-- Returns: `ChainBuilder<Locales, Messages>` — A new builder instance with cloned messages
-
-```ts
-const builder1 = createI18n(['ja', 'en'] as const)
-  .add({
-    title: { ja: 'タイトル', en: 'Title' },
-  });
-
-const builder2 = builder1.clone().add({
-  greeting: { ja: 'こんにちは', en: 'Hello' },
-});
-
-const messages1 = builder1.build('ja');
-const messages2 = builder2.build('ja');
-
-console.log(messages1.title.render());    // "タイトル"
-console.log(messages1.greeting);          // undefined
-
-console.log(messages2.title.render());    // "タイトル"
-console.log(messages2.greeting.render()); // "こんにちは"
-```
-
-**Note**: `clone()` creates a deep copy of all messages, allowing you to branch off from a base builder and add different messages independently.
-
-### `I18nMessage<Locales, Context, ReturnType = string>`
-Represents a single localized message.
-
-#### Properties
-- `locales: Locales` — Readonly array of allowed locales
-- `locale: Locale` — Current active locale (getter)
-- `data: Record<Locale, Template<Context, ReturnType>>` — Message data for all locales (getter)
-
-#### Methods
-- `setLocale(locale: Locale): this` — Sets the active locale
-- `setData(data: Record<Locale, Template<Context, ReturnType>>): this` — Sets the message data
-- `render(ctx?: Context): ReturnType` — Renders the message for the active locale and returns the specified type
-
-```ts
-const message = messages.title;
-console.log(message.locale);           // Current locale
-console.log(message.render());         // Rendered string
-
-message.setLocale('ja');
-console.log(message.render());         // Japanese version
-```
-
 ### `bindLocale(obj, locale)`
 Recursively traverses objects/arrays and sets the given locale on all `I18nMessage` instances and builds all `ChainBuilder` instances encountered.
 
@@ -291,8 +246,8 @@ const data = {
 };
 
 const localized = bindLocale(data, 'en');
-console.log(localized.common.title.render());      // English version
-console.log(localized.nested.special.msg.render()); // English version
+console.log(localized.common.title());      // English version
+console.log(localized.nested.special.msg()); // English version
 ```
 
 **Note**: `bindLocale` works with both `ChainBuilder` instances (automatically building them with the specified locale) and already-built message objects (updating their locale).
@@ -315,91 +270,6 @@ export type { Template, LocalizedMessage } from 'canopy-i18n';
 
 ## Usage Patterns
 
-### React Components as Messages
-
-```ts
-import { createI18n } from 'canopy-i18n';
-
-// Static React components
-const messages = createI18n(['ja', 'en'] as const)
-  .add<JSX.Element>({
-    badge: {
-      ja: <span style={{ background: '#4caf50', color: 'white', padding: '4px 8px', borderRadius: '4px' }}>新着</span>,
-      en: <span style={{ background: '#4caf50', color: 'white', padding: '4px 8px', borderRadius: '4px' }}>NEW</span>,
-    },
-    alert: {
-      ja: <div style={{ background: '#fff3cd', padding: '12px', borderRadius: '4px' }}>⚠️ これは警告です</div>,
-      en: <div style={{ background: '#fff3cd', padding: '12px', borderRadius: '4px' }}>⚠️ This is a warning</div>,
-    },
-  })
-  .build('en');
-
-// Render in React
-function MyComponent() {
-  return (
-    <div>
-      {messages.badge.render()}
-      {messages.alert.render()}
-    </div>
-  );
-}
-
-// Dynamic React components with context
-type ButtonContext = {
-  onClick: () => void;
-  text: string;
-};
-
-const dynamicMessages = createI18n(['ja', 'en'] as const)
-  .addTemplates<ButtonContext, JSX.Element>()({
-    button: {
-      ja: (ctx) => (
-        <button onClick={ctx.onClick} style={{ background: '#2196f3', color: 'white', padding: '8px 16px' }}>
-          {ctx.text}
-        </button>
-      ),
-      en: (ctx) => (
-        <button onClick={ctx.onClick} style={{ background: '#2196f3', color: 'white', padding: '8px 16px' }}>
-          {ctx.text}
-        </button>
-      ),
-    },
-  })
-  .build('en');
-
-// Use with context
-function AnotherComponent() {
-  return <div>{dynamicMessages.button.render({ onClick: () => alert('Clicked!'), text: 'Click me' })}</div>;
-}
-```
-
-### Custom Object Types
-
-```ts
-type MenuItem = {
-  label: string;
-  url: string;
-  icon: string;
-};
-
-const menuMessages = createI18n(['ja', 'en'] as const)
-  .add<MenuItem>({
-    home: {
-      ja: { label: 'ホーム', url: '/', icon: '🏠' },
-      en: { label: 'Home', url: '/', icon: '🏠' },
-    },
-    settings: {
-      ja: { label: '設定', url: '/settings', icon: '⚙️' },
-      en: { label: 'Settings', url: '/settings', icon: '⚙️' },
-    },
-  })
-  .build('en');
-
-const homeMenu = menuMessages.home.render();
-console.log(homeMenu.label); // "Home"
-console.log(homeMenu.url);   // "/"
-console.log(homeMenu.icon);  // "🏠"
-```
 
 ### Basic String Messages
 
@@ -412,8 +282,8 @@ const messages = createI18n(['ja', 'en'] as const)
   })
   .build('en');
 
-console.log(messages.title.render());    // "Title"
-console.log(messages.greeting.render()); // "Hello"
+console.log(messages.title());    // "Title"
+console.log(messages.greeting()); // "Hello"
 ```
 
 ### Template Functions with Context
@@ -428,7 +298,7 @@ const messages = createI18n(['ja', 'en'] as const)
   })
   .build('en');
 
-console.log(messages.profile.render({ name: 'Taro', age: 25 }));
+console.log(messages.profile({ name: 'Taro', age: 25 }));
 // "Name: Taro, Age: 25"
 ```
 
@@ -447,39 +317,11 @@ const messages = createI18n(['ja', 'en'] as const)
   })
   .build('ja');
 
-console.log(messages.title.render());           // "タイトル"
-console.log(messages.items.render({ count: 5 })); // "5個のアイテム"
+console.log(messages.title());           // "タイトル"
+console.log(messages.items({ count: 5 })); // "5個のアイテム"
 ```
 
-### Using Clone for Shared Base Messages
-
-```ts
-// Create a base builder with common messages
-const baseBuilder = createI18n(['ja', 'en'] as const)
-  .add({
-    common: { ja: '共通', en: 'Common' },
-    error: { ja: 'エラー', en: 'Error' },
-  });
-
-// Clone and extend for admin pages
-const adminMessages = baseBuilder.clone()
-  .add({
-    adminTitle: { ja: '管理画面', en: 'Admin Panel' },
-  })
-  .build('en');
 
-// Clone and extend for user pages
-const userMessages = baseBuilder.clone()
-  .add({
-    userTitle: { ja: 'ユーザー画面', en: 'User Panel' },
-  })
-  .build('en');
-
-console.log(adminMessages.common.render());     // "Common"
-console.log(adminMessages.adminTitle.render()); // "Admin Panel"
-console.log(userMessages.common.render());      // "Common"
-console.log(userMessages.userTitle.render());   // "User Panel"
-```
 
 ### Namespace Pattern (Split Files)
 
@@ -516,8 +358,8 @@ import { bindLocale } from 'canopy-i18n';
 import * as i18n from './i18n';
 
 const messages = bindLocale(i18n, 'en');
-console.log(messages.common.hello.render());              // "Hello"
-console.log(messages.user.welcome.render({ name: 'John' })); // "Welcome, John"
+console.log(messages.common.hello());              // "Hello"
+console.log(messages.user.welcome({ name: 'John' })); // "Welcome, John"
 ```
 
 ### Dynamic Locale Switching
@@ -532,13 +374,8 @@ const builder = createI18n(['ja', 'en'] as const)
 const jaMessages = builder.build('ja');
 const enMessages = builder.build('en');
 
-console.log(jaMessages.title.render()); // "タイトル"
-console.log(enMessages.title.render()); // "Title"
-
-// Or use bindLocale to switch locale dynamically
-const messages = builder.build();
-const localizedJa = bindLocale(messages, 'ja');
-const localizedEn = bindLocale(messages, 'en');
+console.log(jaMessages.title()); // "タイトル"
+console.log(enMessages.title()); // "Title"
 ```
 
 ### Deep Nested Structures
@@ -556,9 +393,9 @@ const structure = {
 };
 
 const localized = bindLocale(structure, 'en');
-console.log(localized.header.title.render());           // "Header"
-console.log(localized.content.main.body.render());      // "Body"
-console.log(localized.content.sidebar.widget.render()); // "Widget"
+console.log(localized.header.title());           // "Header"
+console.log(localized.content.main.body());      // "Body"
+console.log(localized.content.sidebar.widget()); // "Widget"
 ```
 
 

package/dist/bindLocale.d.ts

@@ -1,7 +1,9 @@
 import { ChainBuilder } from "./chainBuilder.js";
-import { I18nMessage } from "./message.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<any, any, any> ? T : T extends ChainBuilder<any, infer Messages> ? Messages : T extends readonly 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;
+} : T extends readonly any[] ? {
     [K in keyof T]: DeepUnwrapChainBuilders<T[K]>;
 } : T extends object ? {
     [K in keyof T]: DeepUnwrapChainBuilders<T[K]>;

package/dist/bindLocale.js

@@ -9,8 +9,10 @@ export function bindLocale(obj, locale) {
             return v.build(locale);
         }
         if (isI18nMessage(v)) {
-            v.setLocale(locale);
-            return v;
+            const cloned = Object.create(Object.getPrototypeOf(v));
+            Object.assign(cloned, v);
+            cloned.setLocale(locale);
+            return cloned.toFunction();
         }
         if (Array.isArray(v)) {
             return v.map(visit);

package/dist/chainBuilder.d.ts

@@ -11,7 +11,7 @@ export declare class ChainBuilder<const Ls extends readonly string[], Messages e
     add<R = string, Entries extends Record<string, Record<Ls[number], R>> = Record<string, Record<Ls[number], R>>>(entries: {
         [K in keyof Entries]: K extends keyof Messages ? never : Entries[K];
     }): ChainBuilder<Ls, Messages & {
-        [K in keyof Entries]: LocalizedMessage<Ls, void, R>;
+        [K in keyof Entries]: I18nMessage<Ls, void, R>;
     }>;
     /**
      * 関数指定版: 複数のテンプレート関数を一度に追加(型は統一)
@@ -19,13 +19,11 @@ export declare class ChainBuilder<const Ls extends readonly string[], Messages e
     addTemplates<C, R = string>(): <Entries extends Record<string, Record<Ls[number], (ctx: C) => R>>>(entries: {
         [K in keyof Entries]: K extends keyof Messages ? never : Entries[K];
     }) => ChainBuilder<Ls, Messages & {
-        [K in keyof Entries]: LocalizedMessage<Ls, C, R>;
+        [K in keyof Entries]: I18nMessage<Ls, C, R>;
     }>;
     private deepCloneWithLocale;
-    build(locale?: Ls[number]): Messages;
-    /**
-     * 現在のChainBuilderの状態をコピーした新しいインスタンスを返す
-     */
-    clone(): ChainBuilder<Ls, Messages>;
+    build<M = {
+        [K in keyof Messages]: Messages[K] extends I18nMessage<Ls, infer C, infer R> ? LocalizedMessage<Ls, C, R> : never;
+    }>(locale?: Ls[number]): M;
 }
 export declare function createI18n<const Ls extends readonly string[]>(locales: Ls): ChainBuilder<Ls, {}>;

package/dist/chainBuilder.js

@@ -51,28 +51,19 @@ export class ChainBuilder {
         return obj;
     }
     build(locale) {
-        if (locale !== undefined) {
-            return this.deepCloneWithLocale(this.messages, locale);
-        }
-        return this.messages;
-    }
-    /**
-     * 現在のChainBuilderの状態をコピーした新しいインスタンスを返す
-     */
-    clone() {
-        const clonedMessages = {};
-        for (const [key, msg] of Object.entries(this.messages)) {
+        const clonedMessages = locale !== undefined
+            ? this.deepCloneWithLocale(this.messages, locale)
+            : this.messages;
+        const result = {};
+        for (const [key, msg] of Object.entries(clonedMessages)) {
             if (isI18nMessage(msg)) {
-                // I18nMessageをクローン
-                const cloned = Object.create(Object.getPrototypeOf(msg));
-                Object.assign(cloned, msg);
-                clonedMessages[key] = cloned;
+                result[key] = msg.toFunction();
             }
             else {
-                clonedMessages[key] = msg;
+                result[key] = msg;
             }
         }
-        return new ChainBuilder(this.locales, clonedMessages);
+        return result;
     }
 }
 export function createI18n(locales) {

package/dist/message.d.ts

@@ -1,5 +1,9 @@
 import type { Template } from "./types.js";
-export type LocalizedMessage<Ls extends readonly string[], C, R = string> = I18nMessage<Ls, C, R>;
+export type LocalizedMessage<Ls extends readonly string[], C, R = string> = C extends void ? (() => R) & {
+    __brand: "I18nMessage";
+} : ((ctx: C) => R) & {
+    __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> {
     readonly locales: Ls;
@@ -10,6 +14,6 @@ export declare class I18nMessage<Ls extends readonly string[], C, R = string> {
     setLocale(locale: Ls[number]): this;
     get data(): Record<Ls[number], Template<C, R>>;
     setData(data: Record<Ls[number], Template<C, R>>): this;
-    render(this: I18nMessage<Ls, void, R>): R;
-    render(ctx: C): R;
+    private render;
+    toFunction(): LocalizedMessage<Ls, C, R>;
 }

package/dist/message.js

@@ -31,4 +31,9 @@ export class I18nMessage {
         }
         return v;
     }
+    toFunction() {
+        const self = this;
+        const fn = ((ctx) => self.render(ctx));
+        return fn;
+    }
 }

package/dist/testtest.d.ts

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

package/dist/testtest.js

@@ -0,0 +1,14 @@
+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` },
+});
+const c = b.build("en");
+const e = { ...c.abc, toString: () => "aaa" };
+console.log(c.bb({ aa: "name" }));
+console.log(`${c.bb({ aa: "name" })}`);
+console.log("aaa" + c.bb({ aa: "name" }));
+console.log(`${c.bb({ aa: "name" })}`);
+console.log(`${c.abc()}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "canopy-i18n",
-  "version": "0.4.2",
-  "description": "A tiny, type-safe i18n helper",
+  "version": "0.5.1",
+  "description": "The Type-Safe i18n library that your IDE will Love",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,14 +25,15 @@
     "prepublishOnly": "pnpm run build",
     "type-check": "tsc -p . --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "release": "release-it"
   },
   "devDependencies": {
     "@tsconfig/node20": "^20.1.8",
-    "@types/node": "^24.10.4",
-    "release-it": "^19.2.2",
+    "@types/node": "^25.0.10",
+    "release-it": "^19.2.4",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.18"
   },
   "keywords": [
     "i18n",
@@ -48,6 +49,6 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/MOhhh-ok/canopy-i18n"
+    "url": "https://github.com/mohhh-ok/canopy-i18n"
   }
 }