canopy-i18n 0.1.1 → 0.3.0

package/README.md

@@ -1,13 +1,14 @@
-## canopy-i18n
+# canopy-i18n
 
-A tiny, type-safe i18n helper for building localized messages and applying a locale across nested data structures.
+A tiny, type-safe i18n library for building localized messages with builder pattern and applying locales across nested data structures.
 
-### Features
+## Features
 - **Type-safe locales**: Compile-time safety for allowed locale keys.
-- **Per-message fallback**: Each message knows its default and fallback locale.
-- **Template or string**: Use plain strings or `(ctx) => string` templates.
-- **Flexible templating**: Since templates are plain functions, you can freely use JavaScript template literals, conditionals, helpers, or any formatting library. This library does not provide a tagged template literal API.
-- **Deep locale application**: Switch locale across entire object/array trees.
+- **Builder pattern**: Chain methods to build multiple messages at once.
+- **String or template functions**: Use plain strings or `(ctx) => string` templates.
+- **Flexible templating**: Templates are plain functions, so you can freely use JavaScript template literals, conditionals, helpers, or any formatting library.
+- **Generic return types**: Return any type (string, React components, etc.) from your messages.
+- **Deep locale application**: Switch locale across entire object/array trees, including nested builders.
 
 ## Installation
 
@@ -17,179 +18,485 @@ npm install canopy-i18n
 pnpm add canopy-i18n
 # or
 yarn add canopy-i18n
+# or
+bun add canopy-i18n
 ```
 
-## Quick start
+## Quick Start
 
 ```ts
-import { createI18n, applyLocale } from 'canopy-i18n';
+import { createI18n, bindLocale } from 'canopy-i18n';
+
+// 1) Create a builder with allowed locales
+const baseBuilder = createI18n(['ja', 'en'] as const);
+
+// 2) Define messages using method chaining (store in a variable)
+const builder = baseBuilder
+  .add({
+    title: {
+      ja: 'タイトルテスト',
+      en: 'Title Test',
+    },
+    greeting: {
+      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.`,
+    },
+  });
+
+// 3) Reuse the builder to create messages for different locales
+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."
+
+// 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歳です。"
+```
 
-// 1) Declare allowed locales and fallback
-const defineMessage = createI18n(['ja', 'en'] as const, 'ja');
+## API
 
-// 2) Define messages
-const title = defineMessage({
-  ja: 'タイトルテスト',
-  en: 'Title Test',
-});
+### `createI18n(locales)`
+Creates a `ChainBuilder` instance to build localized messages.
 
-const msg = defineMessage<{ name: string; age: number }>({
-  ja: c => `こんにちは、${c.name}さん。あなたは${c.age}歳です。`,
-  en: c => `Hello, ${c.name}. You are ${c.age} years old.`,
-});
+- **locales**: `readonly string[]` — Allowed locale keys (e.g. `['ja', 'en'] as const`).
+- Returns: `ChainBuilder<Locales, {}>` — A builder instance to chain message definitions.
 
-// 3) Compose nested data structures
-const data = {
-  title,
-  nested: {
-    hello: defineMessage({ ja: 'こんにちは', en: 'Hello' }),
-  },
+```ts
+const builder = createI18n(['ja', 'en', 'fr'] as const);
+```
+
+### `ChainBuilder`
+A builder class for creating multiple localized messages with method chaining.
+
+#### `.add<ReturnType = string>(entries)`
+Adds multiple messages at once. By default, returns `string`, but you can specify a custom return type.
+
+- **ReturnType**: (optional) Type parameter for the return value (defaults to `string`)
+- **entries**: `Record<string, Record<Locale, ReturnType>>`
+- Returns: `ChainBuilder` with added messages
+
+```ts
+// String messages (default)
+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={{ color: 'red' }}>新着</span>,
+      en: <span style={{ color: 'red' }}>NEW</span>,
+    },
+  });
+
+// Custom return type (objects)
+type MenuItem = {
+  label: string;
+  url: string;
 };
 
-// 4) Apply locale across the tree
-const localized = applyLocale(data, 'en');
+const menu = createI18n(['ja', 'en'] as const)
+  .add<MenuItem>({
+    home: {
+      ja: { label: 'ホーム', url: '/' },
+      en: { label: 'Home', url: '/' },
+    },
+  });
+```
+
+#### `.addTemplates<Context, ReturnType = 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>()` 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`)
+- **entries**: `Record<string, 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}.`,
+    },
+  });
+```
+
+
+
+#### `.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.
+- Returns: `Messages` — An object containing all defined messages
 
-console.log(localized.title.render());       // "Title Test"
-console.log(localized.nested.hello.render()); // "Hello"
-console.log(msg.setLocale('en').render({ name: 'Tanaka', age: 20 }));
+```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');
 ```
 
-## API
+**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.
 
-### createI18n(locales, fallbackLocale)
-Returns a `defineMessage` function to create localized messages.
+#### `.clone()`
+Creates an independent copy of the current builder with all its 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.
+- Returns: `ChainBuilder<Locales, Messages>` — A new builder instance with cloned messages
 
-Overloads:
-- `defineMessage<Record<L[number], string>>() -> I18nMessage<L, void>`
-- `defineMessage<Record<L[number], Template<C>>>() -> I18nMessage<L, C>`
+```ts
+const builder1 = createI18n(['ja', 'en'] as const)
+  .add({
+    title: { ja: 'タイトル', en: 'Title' },
+  });
 
-### I18nMessage<L, C>
+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: L`
-  - `locale: L[number]` (getter)
-  - `fallbackLocale: L[number]` (getter)
-  - `data: Record<L[number], Template<C>>`
-- **methods**
-  - `setLocale(locale: L[number]): this`
-  - `setFallbackLocale(locale: L[number]): this`
-  - `render(ctx?: C): string` — If the value for the active locale is a function, it’s invoked with `ctx`; otherwise the string is returned. Falls back to `fallbackLocale` if needed.
+#### 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.
 
-### applyLocale(obj, locale)
-Recursively traverses arrays/objects and sets the given `locale` on all `I18nMessage` instances encountered.
+- **obj**: Any object/array structure containing messages or builders
+- **locale**: The locale to apply
+- Returns: A new structure with locale applied (containers are cloned, message instances are updated in place)
+
+```ts
+const data = {
+  common: builder1,
+  nested: {
+    special: builder2,
+  },
+};
+
+const localized = bindLocale(data, 'en');
+console.log(localized.common.title.render());      // English version
+console.log(localized.nested.special.msg.render()); // English version
+```
 
-- Returns a new container (arrays/objects are cloned), but reuses the same message instances after updating their locale.
+**Note**: `bindLocale` works with both `ChainBuilder` instances (automatically building them with the specified locale) and already-built message objects (updating their locale).
 
 ## Types
 
 ```ts
-export type Template<C> = string | ((ctx: C) => string);
+export type Template<C, R = string> = R | ((ctx: C) => R);
+export type LocalizedMessage<Locales, Context, ReturnType = string> = I18nMessage<Locales, Context, ReturnType>;
 ```
 
 ## Exports
 
 ```ts
+export { createI18n, ChainBuilder } from 'canopy-i18n';
 export { I18nMessage, isI18nMessage } 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';
+export { bindLocale, isChainBuilder } from 'canopy-i18n';
+export type { Template, LocalizedMessage } from 'canopy-i18n';
 ```
 
-## Notes
-- CommonJS build (`main: dist/index.js`) with TypeScript type declarations (`types: dist/index.d.ts`).
-- Works in Node or bundlers; recommended usage is TypeScript/ESM import via your build tool.
-- License: MIT.
- - Not a tagged template library: you write plain functions (examples use JS template literals inside those functions).
+## Usage Patterns
 
-### Split files example (namespace import)
-
-Import all message exports as a namespace and set the locale across the whole tree.
+### React Components as Messages
 
 ```ts
-// messages.ts
 import { createI18n } from 'canopy-i18n';
-const defineMessage = createI18n(['ja', 'en'] as const, 'ja');
 
-export const title = defineMessage({
-  ja: 'タイトルテスト',
-  en: 'Title Test',
-});
+// 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;
+};
 
-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.`,
-});
+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>;
+}
 ```
 
-```ts
-// usage.ts
-import * as messages from './messages';
-import { applyLocale } from 'canopy-i18n';
+### Custom Object Types
 
-const m = applyLocale(messages, 'en');
+```ts
+type MenuItem = {
+  label: string;
+  url: string;
+  icon: string;
+};
 
-console.log(m.title.render());                     // "Title Test"
-console.log(m.msg.render({ name: 'Tanaka', age: 20 }));
+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);  // "🏠"
 ```
 
-#### Multi-file structure
+### Basic String Messages
 
 ```ts
-// i18n/defineMessage.ts
-import { createI18n } from 'canopy-i18n';
-export const defineMessage = createI18n(['ja', 'en'] as const, 'ja');
+const messages = createI18n(['ja', 'en'] as const)
+  .add({
+    title: { ja: 'タイトル', en: 'Title' },
+    greeting: { ja: 'こんにちは', en: 'Hello' },
+    farewell: { ja: 'さようなら', en: 'Goodbye' },
+  })
+  .build('en');
+
+console.log(messages.title.render());    // "Title"
+console.log(messages.greeting.render()); // "Hello"
 ```
 
+### Template Functions with Context
+
 ```ts
-// i18n/messages/common.ts
-import { defineMessage } from '../defineMessage';
-export const hello = defineMessage({ ja: 'こんにちは', en: 'Hello' });
+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}`,
+    },
+  })
+  .build('en');
+
+console.log(messages.profile.render({ name: 'Taro', age: 25 }));
+// "Name: Taro, Age: 25"
 ```
 
+### Mixing String and Template Messages
+
 ```ts
-// i18n/messages/home.ts
-import { defineMessage } from '../defineMessage';
-export const title = defineMessage({ ja: 'タイトル', en: 'Title' });
+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`,
+    },
+  })
+  .build('ja');
+
+console.log(messages.title.render());           // "タイトル"
+console.log(messages.items.render({ count: 5 })); // "5個のアイテム"
 ```
 
+### Using Clone for Shared Base Messages
+
 ```ts
-// i18n/messages/index.ts
-export * as common from './common';
-export * as home from './home';
+// 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)
+
 ```ts
-// usage.ts
-import * as msgs from './i18n/messages';
-import { applyLocale } from 'canopy-i18n';
+// i18n/locales.ts
+export const LOCALES = ['ja', 'en'] as const;
 
-const m = applyLocale(msgs, 'en');
+// i18n/common.ts
+import { createI18n } from 'canopy-i18n';
+import { LOCALES } from './locales';
 
-console.log(m.common.hello.render()); // "Hello"
-console.log(m.home.title.render());   // "Title"
-```
+export const common = createI18n(LOCALES).add({
+  hello: { ja: 'こんにちは', en: 'Hello' },
+  goodbye: { ja: 'さようなら', en: 'Goodbye' },
+});
 
-Note: Module namespace objects are read-only; `applyLocale` returns a cloned plain object while updating each `I18nMessage` instance's locale in place.
+// i18n/user.ts
+import { createI18n } from 'canopy-i18n';
+import { LOCALES } from './locales';
 
-## Example: Next.js App Router
+export const user = createI18n(LOCALES).addTemplates<{ name: string }>()({
+  welcome: {
+    ja: (ctx) => `ようこそ、${ctx.name}さん`,
+    en: (ctx) => `Welcome, ${ctx.name}`,
+  },
+});
 
-An example Next.js App Router project lives under `examples/next-app`.
+// i18n/index.ts
+export { common } from './common';
+export { user } from './user';
 
-- Server-side usage: `/{locale}/server` renders messages using `applyLocale` in a server component
-- Client-side usage: `/{locale}/client` renders messages using hooks (`useLocale`, `useApplyLocale`)
+// app.ts
+import { bindLocale } from 'canopy-i18n';
+import * as i18n from './i18n';
 
-How to run:
+const messages = bindLocale(i18n, 'en');
+console.log(messages.common.hello.render());              // "Hello"
+console.log(messages.user.welcome.render({ name: 'John' })); // "Welcome, John"
+```
 
-```bash
-git clone https://github.com/mohhh-ok/canopy-i18n
-cd canopy-i18n/examples/next-app
-pnpm install
-pnpm dev
+### Dynamic Locale Switching
+
+```ts
+const builder = createI18n(['ja', 'en'] as const)
+  .add({
+    title: { ja: 'タイトル', en: 'Title' },
+  });
+
+// Build different locale versions from the same builder
+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');
+```
+
+### Deep Nested Structures
+
+```ts
+const structure = {
+  header: createI18n(['ja', 'en'] as const)
+    .add({ title: { ja: 'ヘッダー', en: 'Header' } }),
+  content: {
+    main: createI18n(['ja', 'en'] as const)
+      .add({ body: { ja: '本文', en: 'Body' } }),
+    sidebar: createI18n(['ja', 'en'] as const)
+      .add({ widget: { ja: 'ウィジェット', en: 'Widget' } }),
+  },
+};
+
+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"
 ```
 
-Open `http://localhost:3000` and you will be redirected to `/{locale}` based on `Accept-Language`.
+
+## Repository
+
+https://github.com/MOhhh-ok/canopy-i18n

package/dist/bindLocale.d.ts

@@ -0,0 +1,10 @@
+import { ChainBuilder } from "./chainBuilder";
+import { I18nMessage } from "./message";
+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[] ? {
+    [K in keyof T]: DeepUnwrapChainBuilders<T[K]>;
+} : T extends object ? {
+    [K in keyof T]: DeepUnwrapChainBuilders<T[K]>;
+} : T;
+export declare function bindLocale<T extends object>(obj: T, locale: string): DeepUnwrapChainBuilders<T>;
+export {};

package/dist/{applyLocale.js → bindLocale.js}

@@ -1,9 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyLocale = applyLocale;
+exports.isChainBuilder = isChainBuilder;
+exports.bindLocale = bindLocale;
+const chainBuilder_1 = require("./chainBuilder");
 const message_1 = require("./message");
-function applyLocale(obj, locale) {
+function isChainBuilder(x) {
+    return x instanceof chainBuilder_1.ChainBuilder;
+}
+function bindLocale(obj, locale) {
     function visit(v) {
+        if (isChainBuilder(v)) {
+            return v.build(locale);
+        }
         if ((0, message_1.isI18nMessage)(v)) {
             v.setLocale(locale);
             return v;
@@ -11,7 +19,7 @@ function applyLocale(obj, locale) {
         if (Array.isArray(v)) {
             return v.map(visit);
         }
-        if (v && typeof v === 'object') {
+        if (v && typeof v === "object") {
             const out = {};
             for (const k of Object.keys(v)) {
                 out[k] = visit(v[k]);

package/dist/chainBuilder.d.ts

@@ -0,0 +1,31 @@
+import { I18nMessage } from "./message";
+import type { LocalizedMessage } from "./message";
+export declare class ChainBuilder<const Ls extends readonly string[], Messages extends Record<string, I18nMessage<Ls, any, any>> = {}> {
+    private readonly locales;
+    private messages;
+    constructor(locales: Ls, messages?: Messages);
+    /**
+     * 複数のメッセージを一度に追加
+     * 型パラメータRでカスタム型も指定可能(デフォルトはstring)
+     */
+    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>;
+    }>;
+    /**
+     * 関数指定版: 複数のテンプレート関数を一度に追加(型は統一)
+     */
+    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>;
+    }>;
+    private deepCloneWithLocale;
+    build(locale?: Ls[number]): Messages;
+    /**
+     * 現在のChainBuilderの状態をコピーした新しいインスタンスを返す
+     */
+    clone(): ChainBuilder<Ls, Messages>;
+}
+export declare function createI18n<const Ls extends readonly string[]>(locales: Ls): ChainBuilder<Ls, {}>;

package/dist/chainBuilder.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChainBuilder = void 0;
+exports.createI18n = createI18n;
+const message_1 = require("./message");
+class ChainBuilder {
+    locales;
+    messages;
+    constructor(locales, messages) {
+        this.locales = locales;
+        this.messages = (messages ?? {});
+    }
+    /**
+     * 複数のメッセージを一度に追加
+     * 型パラメータRでカスタム型も指定可能(デフォルトはstring)
+     */
+    add(entries) {
+        const newMessages = { ...this.messages };
+        for (const [key, data] of Object.entries(entries)) {
+            const msg = new message_1.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 message_1.I18nMessage(this.locales, this.locales[0]).setData(data);
+                newMessages[key] = msg;
+            }
+            return new ChainBuilder(this.locales, newMessages);
+        };
+    }
+    deepCloneWithLocale(obj, locale) {
+        if ((0, message_1.isI18nMessage)(obj)) {
+            const cloned = Object.create(Object.getPrototypeOf(obj));
+            Object.assign(cloned, obj);
+            cloned.setLocale(locale);
+            return cloned;
+        }
+        if (Array.isArray(obj)) {
+            return obj.map(v => this.deepCloneWithLocale(v, locale));
+        }
+        if (obj && typeof obj === "object") {
+            const out = {};
+            for (const k of Object.keys(obj)) {
+                out[k] = this.deepCloneWithLocale(obj[k], locale);
+            }
+            return out;
+        }
+        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)) {
+            if ((0, message_1.isI18nMessage)(msg)) {
+                // I18nMessageをクローン
+                const cloned = Object.create(Object.getPrototypeOf(msg));
+                Object.assign(cloned, msg);
+                clonedMessages[key] = cloned;
+            }
+            else {
+                clonedMessages[key] = msg;
+            }
+        }
+        return new ChainBuilder(this.locales, clonedMessages);
+    }
+}
+exports.ChainBuilder = ChainBuilder;
+function createI18n(locales) {
+    return new ChainBuilder(locales);
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { applyLocale } from './applyLocale';
-export { createI18n } from './createI18n';
-export { I18nMessage, isI18nMessage } from './message';
-export type { LocalizedMessage } from './message';
-export type { Template } from './types';
+export { bindLocale, isChainBuilder } from "./bindLocale";
+export { ChainBuilder, createI18n } from "./chainBuilder";
+export { I18nMessage, isI18nMessage } from "./message";
+export type { LocalizedMessage } from "./message";
+export type { Template } from "./types";

package/dist/index.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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; } });
+exports.isI18nMessage = exports.I18nMessage = exports.createI18n = exports.ChainBuilder = exports.isChainBuilder = exports.bindLocale = void 0;
+var bindLocale_1 = require("./bindLocale");
+Object.defineProperty(exports, "bindLocale", { enumerable: true, get: function () { return bindLocale_1.bindLocale; } });
+Object.defineProperty(exports, "isChainBuilder", { enumerable: true, get: function () { return bindLocale_1.isChainBuilder; } });
+var chainBuilder_1 = require("./chainBuilder");
+Object.defineProperty(exports, "ChainBuilder", { enumerable: true, get: function () { return chainBuilder_1.ChainBuilder; } });
+Object.defineProperty(exports, "createI18n", { enumerable: true, get: function () { return chainBuilder_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; } });

package/dist/message.d.ts

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

package/dist/message.js

@@ -2,33 +2,25 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.I18nMessage = void 0;
 exports.isI18nMessage = isI18nMessage;
-function isTemplateFunction(t) {
-    return typeof t === 'function';
+const types_1 = require("./types");
+function isI18nMessage(x) {
+    return x instanceof I18nMessage;
 }
 class I18nMessage {
     locales;
     _locale;
-    _fallbackLocale;
     _data;
-    constructor(locales, fallbackLocale) {
+    constructor(locales, locale) {
         this.locales = locales;
-        this._fallbackLocale = fallbackLocale;
-        this._locale = fallbackLocale;
+        this._locale = locale;
     }
     get locale() {
         return this._locale;
     }
-    get fallbackLocale() {
-        return this._fallbackLocale;
-    }
     setLocale(locale) {
         this._locale = locale;
         return this;
     }
-    setFallbackLocale(locale) {
-        this._fallbackLocale = locale;
-        return this;
-    }
     get data() {
         return this._data;
     }
@@ -37,11 +29,11 @@ class I18nMessage {
         return this;
     }
     render(ctx) {
-        const v = this._data[this._locale] ?? this._data[this._fallbackLocale];
-        return isTemplateFunction(v) ? v(ctx) : v;
+        const v = this._data[this._locale];
+        if ((0, types_1.isTemplateFunction)(v)) {
+            return v(ctx);
+        }
+        return v;
     }
 }
 exports.I18nMessage = I18nMessage;
-function isI18nMessage(x) {
-    return x instanceof I18nMessage;
-}

package/dist/types.d.ts

@@ -1 +1,2 @@
-export type Template<C> = string | ((ctx: C) => string);
+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;

package/dist/types.js

@@ -1,2 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTemplateFunction = isTemplateFunction;
+function isTemplateFunction(t) {
+    return typeof t === "function";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopy-i18n",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "A tiny, type-safe i18n helper",
   "type": "commonjs",
   "main": "dist/index.js",
@@ -20,12 +20,20 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "dev": "tsc --watch",
+    "build": "tsc",
+    "prepublishOnly": "pnpm run build",
+    "type-check": "tsc -p . --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
   "devDependencies": {
-    "@tsconfig/node20": "^20.1.7",
-    "@types/node": "^24.10.1",
-    "release-it": "^19.0.6",
+    "@tsconfig/node20": "^20.1.8",
+    "@types/node": "^24.10.4",
+    "release-it": "^19.2.2",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.9"
+    "vitest": "^4.0.16"
   },
   "keywords": [
     "i18n",
@@ -42,12 +50,5 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/MOhhh-ok/canopy-i18n"
-  },
-  "scripts": {
-    "dev": "tsc --watch",
-    "build": "tsc",
-    "type-check": "tsc -p . --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
   }
-}
+}

package/dist/applyLocale.d.ts

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

package/dist/applyLocaleDeep.d.ts

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

package/dist/applyLocaleDeep.js

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

package/dist/builder.d.ts

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

package/dist/builder.js

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

package/dist/createBuilder.d.ts

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

package/dist/createBuilder.js

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

package/dist/createI18n.d.ts

@@ -1,6 +0,0 @@
-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

@@ -1,10 +0,0 @@
-"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/test.d.ts

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

package/dist/test.js

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

package/dist/testData.d.ts

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

package/dist/testData.js

@@ -1,27 +0,0 @@
-"use strict";
-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.createI18n)(['ja', 'en'], 'ja');
-exports.title = builder({
-    ja: 'タイトルテスト',
-    en: 'Title Test'
-});
-exports.msg = builder({
-    ja: c => `こんにちは、${c.name}さん、あなたは${c.age}歳です。来年は${c.age + 1}歳です。`,
-    en: c => `Hello, ${c.name}. You are ${c.age} years old. Next year you will be ${c.age + 1} years old.`
-});
-exports.nested = {
-    hello: builder({
-        ja: 'こんにちは',
-        en: 'Hello'
-    }),
-    world: builder({
-        ja: '世界',
-        en: 'World'
-    })
-};
-exports.hasSentMsg = builder({
-    ja: o => `${o.email}にメールを送信しました。確認の上、処理を進めて下さい。`,
-    en: o => `Email sent to ${o.email}. Please check and proceed with the process.`
-});