@simplix-react/i18n 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,206 @@
+# @simplix-react/i18n
+
+Internationalization framework with an adapter pattern and built-in i18next integration.
+
+## Installation
+
+```bash
+pnpm add @simplix-react/i18n
+```
+
+### Peer Dependencies
+
+| Package | Version | Required |
+| --- | --- | --- |
+| `i18next` | >= 25.0.0 | Optional |
+| `react` | >= 18.0.0 | Optional |
+| `react-i18next` | >= 16.0.0 | Optional |
+
+Install the peers you need based on your usage:
+
+```bash
+# Core only (i18next adapter)
+pnpm add i18next
+
+# With React bindings
+pnpm add i18next react react-i18next
+```
+
+## Quick Example
+
+```ts
+import { createI18nConfig } from "@simplix-react/i18n";
+
+const appTranslations = import.meta.glob("./locales/**/*.json", { eager: true });
+
+const { adapter, i18nReady } = createI18nConfig({
+  defaultLocale: "ko",
+  appTranslations,
+});
+
+await i18nReady;
+
+adapter.t("common:greeting");          // "안녕하세요"
+adapter.formatCurrency(10000);         // "₩10,000"
+adapter.formatDate(new Date());        // "2025. 1. 15."
+```
+
+## API Overview
+
+### Core (`@simplix-react/i18n`)
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `II18nAdapter` | Interface | Adapter contract for i18n backends |
+| `I18nextAdapter` | Class | i18next-based adapter implementation |
+| `createI18nConfig` | Function | Factory that creates and initializes an adapter |
+| `buildModuleTranslations` | Function | Builds lazy-loadable module translation descriptors |
+| `DEFAULT_LOCALES` | Constant | Built-in locale configs (ko, en, ja) |
+| `SUPPORTED_LOCALES` | Constant | Locale codes from `DEFAULT_LOCALES` |
+| `DATE_TIME_STYLES` | Constant | Date/time formatting style values |
+| `NUMBER_FORMAT_STYLES` | Constant | Number formatting style values |
+| `TEXT_DIRECTIONS` | Constant | Text direction values (ltr, rtl) |
+| `TRANSLATION_LOAD_STATES` | Constant | Translation loading state values |
+
+### React Bindings (`@simplix-react/i18n/react`)
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `I18nProvider` | Component | Provides the adapter via React context |
+| `useTranslation` | Hook | Namespace-scoped translation with auto re-render |
+| `useLocale` | Hook | Returns the active locale with auto re-render |
+| `useI18n` | Hook | Returns the raw adapter from context |
+| `useI18nAdapter` | Hook | Returns the adapter or `null` from context |
+
+## Key Concepts
+
+### Adapter Pattern
+
+The `II18nAdapter` interface decouples your application from any specific i18n library. The built-in `I18nextAdapter` implements this interface using i18next, but you can create a custom adapter for any backend.
+
+```ts
+import { I18nextAdapter } from "@simplix-react/i18n";
+
+const adapter = new I18nextAdapter({
+  defaultLocale: "en",
+  fallbackLocale: "en",
+  resources: {
+    en: { common: { greeting: "Hello, {{name}}!" } },
+    ko: { common: { greeting: "안녕하세요, {{name}}!" } },
+  },
+});
+
+await adapter.initialize();
+
+adapter.t("common:greeting");                    // uses default namespace
+adapter.tn("common", "greeting", { name: "A" }); // namespaced lookup
+adapter.tp("items", 3);                          // plural form
+```
+
+### Module Translations
+
+Use `buildModuleTranslations` to define lazy-loaded, per-component translations. This enables code splitting -- translations are only loaded when their module is used.
+
+```ts
+import { buildModuleTranslations } from "@simplix-react/i18n";
+
+const dashboardTranslations = buildModuleTranslations({
+  namespace: "dashboard",
+  locales: ["en", "ko"],
+  components: {
+    header: {
+      en: () => import("./header/locales/en.json"),
+      ko: () => import("./header/locales/ko.json"),
+    },
+    sidebar: {
+      en: () => import("./sidebar/locales/en.json"),
+      ko: () => import("./sidebar/locales/ko.json"),
+    },
+  },
+});
+```
+
+Pass these to `createI18nConfig` for automatic loading:
+
+```ts
+const { adapter, i18nReady } = createI18nConfig({
+  defaultLocale: "ko",
+  moduleTranslations: [dashboardTranslations],
+});
+```
+
+### Locale Configuration
+
+The package includes built-in locale configs for Korean, English, and Japanese via `DEFAULT_LOCALES`. Provide custom configs to support additional locales:
+
+```ts
+import type { LocaleConfig } from "@simplix-react/i18n";
+
+const customLocales: LocaleConfig[] = [
+  { code: "en", name: "English", englishName: "English", currency: "USD" },
+  { code: "ko", name: "한국어", englishName: "Korean", currency: "KRW" },
+  { code: "zh", name: "中文", englishName: "Chinese", currency: "CNY" },
+];
+
+const { adapter, i18nReady } = createI18nConfig({
+  defaultLocale: "en",
+  supportedLocales: customLocales,
+});
+```
+
+### Formatting
+
+The adapter provides locale-aware formatting powered by the `Intl` API:
+
+```ts
+// Date / Time
+adapter.formatDate(new Date(), { dateStyle: "long" });
+adapter.formatTime(new Date(), { timeStyle: "short", hour12: true });
+adapter.formatDateTime(new Date());
+adapter.formatRelativeTime(pastDate); // "3 hours ago"
+
+// Numbers
+adapter.formatNumber(1234567.89);                              // "1,234,567.89"
+adapter.formatNumber(0.42, { style: "percent" });              // "42%"
+adapter.formatCurrency(9900, "KRW");                           // "₩9,900"
+```
+
+## React Integration
+
+Wrap your app with `I18nProvider` and use the hooks:
+
+```tsx
+import { I18nProvider, useTranslation, useLocale } from "@simplix-react/i18n/react";
+import { createI18nConfig } from "@simplix-react/i18n";
+
+// Setup
+const { adapter, i18nReady } = createI18nConfig({ defaultLocale: "ko" });
+await i18nReady;
+
+// Provider
+function App() {
+  return (
+    <I18nProvider adapter={adapter}>
+      <Dashboard />
+    </I18nProvider>
+  );
+}
+
+// Consumer
+function Dashboard() {
+  const { t, locale } = useTranslation("dashboard");
+  return <h1>{t("title")} ({locale})</h1>;
+}
+
+// Locale-only
+function LocaleBadge() {
+  const locale = useLocale();
+  return <span>{locale}</span>;
+}
+```
+
+## Related Packages
+
+- `@simplix-react/contract` -- Type-safe API contract definitions
+- `@simplix-react/react` -- React Query hooks derived from contracts
+- `@simplix-react/mock` -- MSW handlers and PGlite repositories

package/dist/index.d.ts

@@ -1,26 +1,75 @@
 import { i18n } from 'i18next';
 
+/**
+ * Represents a BCP 47 locale code string (e.g., `"en"`, `"ko"`, `"ja"`).
+ */
 type LocaleCode = string;
+/**
+ * Represents key-value pairs for translation string interpolation.
+ *
+ * @example
+ * ```ts
+ * const values: TranslationValues = { name: "Alice", count: 3, active: true };
+ * adapter.t("greeting", values); // "Hello, Alice!"
+ * ```
+ */
 type TranslationValues = Record<string, string | number | boolean>;
+/**
+ * Provides constant values for date/time formatting styles compatible with the `Intl.DateTimeFormat` API.
+ *
+ * @example
+ * ```ts
+ * import { DATE_TIME_STYLES } from "@simplix-react/i18n";
+ *
+ * adapter.formatDate(new Date(), { dateStyle: DATE_TIME_STYLES.LONG });
+ * ```
+ */
 declare const DATE_TIME_STYLES: {
     readonly FULL: "full";
     readonly LONG: "long";
     readonly MEDIUM: "medium";
     readonly SHORT: "short";
 };
+/**
+ * Represents a date/time formatting style derived from {@link DATE_TIME_STYLES}.
+ */
 type DateTimeStyle = (typeof DATE_TIME_STYLES)[keyof typeof DATE_TIME_STYLES];
+/**
+ * Provides constant values for number formatting styles compatible with the `Intl.NumberFormat` API.
+ *
+ * @example
+ * ```ts
+ * import { NUMBER_FORMAT_STYLES } from "@simplix-react/i18n";
+ *
+ * adapter.formatNumber(1234.5, { style: NUMBER_FORMAT_STYLES.CURRENCY, currency: "USD" });
+ * ```
+ */
 declare const NUMBER_FORMAT_STYLES: {
     readonly DECIMAL: "decimal";
     readonly CURRENCY: "currency";
     readonly PERCENT: "percent";
     readonly UNIT: "unit";
 };
+/**
+ * Represents a number formatting style derived from {@link NUMBER_FORMAT_STYLES}.
+ */
 type NumberFormatStyle = (typeof NUMBER_FORMAT_STYLES)[keyof typeof NUMBER_FORMAT_STYLES];
+/**
+ * Provides constant values for text direction (`"ltr"` or `"rtl"`).
+ */
 declare const TEXT_DIRECTIONS: {
     readonly LTR: "ltr";
     readonly RTL: "rtl";
 };
+/**
+ * Represents a text direction value derived from {@link TEXT_DIRECTIONS}.
+ */
 type TextDirection = (typeof TEXT_DIRECTIONS)[keyof typeof TEXT_DIRECTIONS];
+/**
+ * Defines plural form strings following the CLDR plural rules.
+ *
+ * @see {@link https://cldr.unicode.org/index/cldr-spec/plural-rules | CLDR Plural Rules}
+ */
 interface PluralForms {
     zero?: string;
     one: string;
@@ -29,79 +78,281 @@ interface PluralForms {
     many?: string;
     other: string;
 }
+/**
+ * Configures date/time formatting options passed to `Intl.DateTimeFormat`.
+ */
 interface DateTimeFormatOptions {
+    /** The date formatting style. */
     dateStyle?: DateTimeStyle;
+    /** The time formatting style. */
     timeStyle?: DateTimeStyle;
+    /** Whether to use 12-hour time format. */
     hour12?: boolean;
 }
+/**
+ * Configures number formatting options passed to `Intl.NumberFormat`.
+ */
 interface NumberFormatOptions {
+    /** The number formatting style. */
     style?: NumberFormatStyle;
+    /** ISO 4217 currency code (required when `style` is `"currency"`). */
     currency?: string;
+    /** Unit identifier (required when `style` is `"unit"`). */
     unit?: string;
+    /** Minimum number of fraction digits to display. */
     minimumFractionDigits?: number;
+    /** Maximum number of fraction digits to display. */
     maximumFractionDigits?: number;
 }
+/**
+ * Describes metadata for a single locale including display names, text direction, and default formats.
+ */
 interface LocaleInfo {
+    /** BCP 47 locale code. */
     code: LocaleCode;
+    /** Native name of the locale (e.g., "한국어"). */
     name: string;
+    /** English name of the locale (e.g., "Korean"). */
     englishName: string;
+    /** Text direction for the locale. */
     direction: TextDirection;
+    /** Default date format pattern. */
     dateFormat: string;
+    /** Default time format pattern. */
     timeFormat: string;
+    /** Default ISO 4217 currency code. */
     currency: string;
 }
+/**
+ * Represents a translation namespace identifier used to scope translation keys.
+ */
 type TranslationNamespace = string;
+/**
+ * Provides constant values representing translation resource loading states.
+ */
 declare const TRANSLATION_LOAD_STATES: {
     readonly IDLE: "idle";
     readonly LOADING: "loading";
     readonly LOADED: "loaded";
     readonly ERROR: "error";
 };
+/**
+ * Represents a translation loading state derived from {@link TRANSLATION_LOAD_STATES}.
+ */
 type TranslationLoadState = (typeof TRANSLATION_LOAD_STATES)[keyof typeof TRANSLATION_LOAD_STATES];
 
+/**
+ * Defines the contract for an internationalization adapter.
+ *
+ * Provides translation lookup, locale management, and formatting capabilities.
+ * Implement this interface to integrate a custom i18n backend.
+ *
+ * @see {@link I18nextAdapter} for the built-in i18next implementation.
+ *
+ * @example
+ * ```ts
+ * import type { II18nAdapter } from "@simplix-react/i18n";
+ *
+ * class CustomAdapter implements II18nAdapter {
+ *   // ... implement all required members
+ * }
+ * ```
+ */
 interface II18nAdapter {
+    /** Unique identifier for this adapter implementation. */
     readonly id: string;
+    /** Human-readable name for this adapter. */
     readonly name: string;
+    /** Currently active locale code. */
     readonly locale: LocaleCode;
+    /** Locale code used when a translation key is missing in the active locale. */
     readonly fallbackLocale: LocaleCode;
+    /** List of all locale codes supported by this adapter. */
     readonly availableLocales: LocaleCode[];
+    /**
+     * Initializes the adapter with an optional default locale.
+     * @param defaultLocale - The locale to activate on initialization.
+     */
     initialize(defaultLocale?: LocaleCode): Promise<void>;
+    /** Disposes of the adapter and releases all resources. */
     dispose(): Promise<void>;
+    /**
+     * Changes the active locale.
+     * @param locale - The target locale code.
+     */
     setLocale(locale: LocaleCode): Promise<void>;
+    /**
+     * Returns metadata for the given locale, or `null` if unsupported.
+     * @param locale - The locale code to look up.
+     */
     getLocaleInfo(locale: LocaleCode): LocaleInfo | null;
+    /**
+     * Translates a key with optional interpolation values.
+     * @param key - The translation key.
+     * @param values - Interpolation values.
+     */
     t(key: string, values?: TranslationValues): string;
+    /**
+     * Translates a namespaced key with optional interpolation values.
+     * @param namespace - The translation namespace.
+     * @param key - The translation key within the namespace.
+     * @param values - Interpolation values.
+     */
     tn(namespace: TranslationNamespace, key: string, values?: TranslationValues): string;
+    /**
+     * Translates a key with plural form selection based on count.
+     * @param key - The translation key.
+     * @param count - The count for plural selection.
+     * @param values - Additional interpolation values.
+     */
     tp(key: string, count: number, values?: TranslationValues): string;
+    /**
+     * Checks whether a translation key exists.
+     * @param key - The translation key to check.
+     * @param namespace - Optional namespace to scope the lookup.
+     */
     exists(key: string, namespace?: TranslationNamespace): boolean;
+    /**
+     * Formats a date according to the active locale.
+     * @param date - The date to format.
+     * @param options - Formatting options.
+     */
     formatDate(date: Date, options?: DateTimeFormatOptions): string;
+    /**
+     * Formats a time according to the active locale.
+     * @param date - The date/time to format.
+     * @param options - Formatting options.
+     */
     formatTime(date: Date, options?: DateTimeFormatOptions): string;
+    /**
+     * Formats a date and time together according to the active locale.
+     * @param date - The date/time to format.
+     * @param options - Formatting options.
+     */
     formatDateTime(date: Date, options?: DateTimeFormatOptions): string;
+    /**
+     * Formats a date as a human-readable relative time string (e.g., "3 hours ago").
+     * @param date - The date to compare against the current time.
+     */
     formatRelativeTime(date: Date): string;
+    /**
+     * Formats a number according to the active locale.
+     * @param value - The number to format.
+     * @param options - Formatting options.
+     */
     formatNumber(value: number, options?: NumberFormatOptions): string;
+    /**
+     * Formats a number as a currency string according to the active locale.
+     * @param value - The monetary value to format.
+     * @param currency - ISO 4217 currency code override (defaults to the locale's currency).
+     */
     formatCurrency(value: number, currency?: string): string;
+    /**
+     * Loads translation resources for a given locale and namespace.
+     * @param locale - The target locale code.
+     * @param namespace - The translation namespace.
+     * @param translations - The translation key-value pairs to load.
+     */
     loadTranslations(locale: LocaleCode, namespace: TranslationNamespace, translations: Record<string, string | PluralForms>): void;
+    /**
+     * Returns the loading state of translation resources.
+     * @param locale - The locale to check.
+     * @param namespace - Optional namespace to check (defaults to `"translation"`).
+     */
     getLoadState(locale: LocaleCode, namespace?: TranslationNamespace): TranslationLoadState;
+    /**
+     * Registers a callback invoked whenever the active locale changes.
+     * @param handler - The callback receiving the new locale code.
+     * @returns A function that unregisters the handler when called.
+     */
     onLocaleChange(handler: (locale: LocaleCode) => void): () => void;
 }
 
+/**
+ * Describes the configuration for a single supported locale.
+ *
+ * @example
+ * ```ts
+ * import type { LocaleConfig } from "@simplix-react/i18n";
+ *
+ * const korean: LocaleConfig = {
+ *   code: "ko",
+ *   name: "한국어",
+ *   englishName: "Korean",
+ *   direction: "ltr",
+ *   currency: "KRW",
+ * };
+ * ```
+ */
 interface LocaleConfig {
+    /** BCP 47 locale code. */
     code: LocaleCode;
+    /** Native display name. */
     name: string;
+    /** English display name. */
     englishName: string;
+    /** Text direction (defaults to `"ltr"`). */
     direction?: "ltr" | "rtl";
+    /** Default date format pattern. */
     dateFormat?: string;
+    /** Default time format pattern. */
     timeFormat?: string;
+    /** Default ISO 4217 currency code. */
     currency?: string;
 }
+/**
+ * Represents a nested structure of translation resources keyed by locale, then namespace.
+ *
+ * @example
+ * ```ts
+ * import type { TranslationResources } from "@simplix-react/i18n";
+ *
+ * const resources: TranslationResources = {
+ *   en: { common: { greeting: "Hello" } },
+ *   ko: { common: { greeting: "안녕하세요" } },
+ * };
+ * ```
+ */
 type TranslationResources = Record<LocaleCode, Record<TranslationNamespace, Record<string, unknown>>>;
+/**
+ * Configures the {@link I18nextAdapter} constructor.
+ */
 interface I18nextAdapterOptions {
+    /** Initial locale to use (defaults to `"en"`). */
     defaultLocale?: LocaleCode;
+    /** Fallback locale when a key is missing (defaults to `"en"`). */
     fallbackLocale?: LocaleCode;
+    /** Supported locale configurations. */
     locales?: LocaleConfig[];
+    /** Pre-loaded translation resources. */
     resources?: TranslationResources;
+    /** An existing i18next instance to reuse instead of creating a new one. */
     i18nextInstance?: i18n;
+    /** Enables i18next debug logging. */
     debug?: boolean;
 }
+/**
+ * Implements {@link II18nAdapter} using i18next as the underlying translation engine.
+ *
+ * Provides locale-aware translation, date/time/number formatting via the `Intl` API,
+ * and reactive locale change notifications.
+ *
+ * @example
+ * ```ts
+ * import { I18nextAdapter } from "@simplix-react/i18n";
+ *
+ * const adapter = new I18nextAdapter({
+ *   defaultLocale: "ko",
+ *   resources: {
+ *     ko: { common: { greeting: "안녕하세요, {{name}}!" } },
+ *     en: { common: { greeting: "Hello, {{name}}!" } },
+ *   },
+ * });
+ *
+ * await adapter.initialize();
+ * adapter.tn("common", "greeting", { name: "Alice" }); // "안녕하세요, Alice!"
+ * ```
+ */
 declare class I18nextAdapter implements II18nAdapter {
     readonly id = "i18next";
     readonly name = "i18next Adapter";
@@ -134,46 +385,159 @@ declare class I18nextAdapter implements II18nAdapter {
     loadTranslations(locale: LocaleCode, namespace: TranslationNamespace, translations: Record<string, string | PluralForms>): void;
     getLoadState(locale: LocaleCode, namespace?: TranslationNamespace): TranslationLoadState;
     onLocaleChange(handler: (locale: LocaleCode) => void): () => void;
+    /**
+     * Adds translation resources to the underlying i18next instance, merging with any existing resources.
+     * @param locale - The target locale code.
+     * @param namespace - The translation namespace.
+     * @param resources - The translation key-value pairs to add.
+     */
     addResources(locale: LocaleCode, namespace: TranslationNamespace, resources: Record<string, unknown>): void;
+    /**
+     * Returns the underlying i18next instance for advanced usage or direct integration with `react-i18next`.
+     */
     getI18nextInstance(): i18n;
     private notifyLocaleChange;
 }
 
+/**
+ * Maps locale codes to lazy-loading functions that return translation modules.
+ *
+ * Designed to work with Vite's `import.meta.glob` for code-split translation files.
+ *
+ * @example
+ * ```ts
+ * import type { ComponentTranslations } from "@simplix-react/i18n";
+ *
+ * const translations: ComponentTranslations = {
+ *   en: () => import("./locales/en.json"),
+ *   ko: () => import("./locales/ko.json"),
+ * };
+ * ```
+ */
 interface ComponentTranslations {
     [locale: string]: () => Promise<{
         default: Record<string, unknown>;
     }>;
 }
+/**
+ * Configures the {@link buildModuleTranslations} function.
+ */
 interface BuildModuleTranslationsOptions {
+    /** Namespace prefix for all component translations in this module. */
     namespace: string;
+    /** List of supported locale codes. */
     locales: string[];
+    /** Map of component paths to their locale-specific translation loaders. */
     components: Record<string, ComponentTranslations>;
 }
+/**
+ * Represents the output of {@link buildModuleTranslations}, providing a lazy-loadable
+ * collection of namespaced translations for a module.
+ */
 interface ModuleTranslations {
+    /** The module's translation namespace. */
     namespace: string;
+    /** Supported locale codes. */
     locales: string[];
+    /** Loads all component translations for the given locale. */
     load: (locale: string) => Promise<Record<string, Record<string, unknown>>>;
 }
+/**
+ * Builds a lazy-loadable module translation descriptor from per-component translation loaders.
+ *
+ * Aggregates component-level translations under a shared namespace so they can be
+ * loaded on demand by {@link createI18nConfig}.
+ *
+ * @param options - The module translation configuration.
+ * @returns A {@link ModuleTranslations} descriptor.
+ *
+ * @example
+ * ```ts
+ * import { buildModuleTranslations } from "@simplix-react/i18n";
+ *
+ * const moduleTranslations = buildModuleTranslations({
+ *   namespace: "dashboard",
+ *   locales: ["en", "ko"],
+ *   components: {
+ *     header: {
+ *       en: () => import("./header/locales/en.json"),
+ *       ko: () => import("./header/locales/ko.json"),
+ *     },
+ *   },
+ * });
+ * ```
+ */
 declare function buildModuleTranslations(options: BuildModuleTranslationsOptions): ModuleTranslations;
 
+/**
+ * Configures the {@link createI18nConfig} factory function.
+ */
 interface CreateI18nConfigOptions {
+    /** Initial locale to activate (defaults to `"en"`). */
     defaultLocale?: LocaleCode;
+    /** Fallback locale for missing translations (defaults to `"en"`). */
     fallbackLocale?: LocaleCode;
+    /** Supported locale configurations (defaults to {@link DEFAULT_LOCALES}). */
     supportedLocales?: LocaleConfig[];
+    /** Language detection configuration. */
     detection?: {
         order: string[];
     };
+    /**
+     * Eagerly imported application translations, typically from `import.meta.glob`.
+     *
+     * Keys should follow the pattern `/locales/{namespace}/{locale}.json`.
+     */
     appTranslations?: Record<string, unknown>;
+    /** Lazy-loadable module translation descriptors built via {@link buildModuleTranslations}. */
     moduleTranslations?: ModuleTranslations[];
+    /** Enables i18next debug logging. */
     debug?: boolean;
 }
+/**
+ * Represents the result of {@link createI18nConfig}.
+ */
 interface I18nConfigResult {
+    /** The configured i18next adapter instance. */
     adapter: I18nextAdapter;
+    /** A promise that resolves when all translations (including module translations) are loaded. */
     i18nReady: Promise<void>;
 }
+/**
+ * Creates and initializes an i18n configuration with an {@link I18nextAdapter}.
+ *
+ * Handles eager loading of app-level translations and lazy loading of module translations.
+ * Returns both the adapter instance and a promise that resolves when initialization is complete.
+ *
+ * @param options - The i18n configuration options.
+ * @returns An {@link I18nConfigResult} containing the adapter and a readiness promise.
+ *
+ * @example
+ * ```ts
+ * import { createI18nConfig } from "@simplix-react/i18n";
+ *
+ * const appTranslations = import.meta.glob("./locales/**\/*.json", { eager: true });
+ *
+ * const { adapter, i18nReady } = createI18nConfig({
+ *   defaultLocale: "ko",
+ *   appTranslations,
+ * });
+ *
+ * await i18nReady;
+ * adapter.t("common:greeting"); // "안녕하세요"
+ * ```
+ */
 declare function createI18nConfig(options: CreateI18nConfigOptions): I18nConfigResult;
 
+/**
+ * Provides built-in locale configurations for Korean, English, and Japanese.
+ *
+ * Used as the default value for `supportedLocales` in {@link createI18nConfig}.
+ */
 declare const DEFAULT_LOCALES: LocaleConfig[];
+/**
+ * Lists the locale codes from {@link DEFAULT_LOCALES} (`["ko", "en", "ja"]`).
+ */
 declare const SUPPORTED_LOCALES: string[];
 
 export { type BuildModuleTranslationsOptions, type ComponentTranslations, type CreateI18nConfigOptions, DATE_TIME_STYLES, DEFAULT_LOCALES, type DateTimeFormatOptions, type DateTimeStyle, type I18nConfigResult, I18nextAdapter, type I18nextAdapterOptions, type II18nAdapter, type LocaleCode, type LocaleConfig, type LocaleInfo, type ModuleTranslations, NUMBER_FORMAT_STYLES, type NumberFormatOptions, type NumberFormatStyle, type PluralForms, SUPPORTED_LOCALES, TEXT_DIRECTIONS, TRANSLATION_LOAD_STATES, type TextDirection, type TranslationLoadState, type TranslationNamespace, type TranslationResources, type TranslationValues, buildModuleTranslations, createI18nConfig };

package/dist/index.js

@@ -249,9 +249,18 @@ var I18nextAdapter = class {
       this.localeChangeHandlers.delete(handler);
     };
   }
+  /**
+   * Adds translation resources to the underlying i18next instance, merging with any existing resources.
+   * @param locale - The target locale code.
+   * @param namespace - The translation namespace.
+   * @param resources - The translation key-value pairs to add.
+   */
   addResources(locale, namespace, resources) {
     this.i18n.addResourceBundle(locale, namespace, resources, true, true);
   }
+  /**
+   * Returns the underlying i18next instance for advanced usage or direct integration with `react-i18next`.
+   */
   getI18nextInstance() {
     return this.i18n;
   }

package/dist/react.d.ts

@@ -1,27 +1,76 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
+/**
+ * Represents a BCP 47 locale code string (e.g., `"en"`, `"ko"`, `"ja"`).
+ */
 type LocaleCode = string;
+/**
+ * Represents key-value pairs for translation string interpolation.
+ *
+ * @example
+ * ```ts
+ * const values: TranslationValues = { name: "Alice", count: 3, active: true };
+ * adapter.t("greeting", values); // "Hello, Alice!"
+ * ```
+ */
 type TranslationValues = Record<string, string | number | boolean>;
+/**
+ * Provides constant values for date/time formatting styles compatible with the `Intl.DateTimeFormat` API.
+ *
+ * @example
+ * ```ts
+ * import { DATE_TIME_STYLES } from "@simplix-react/i18n";
+ *
+ * adapter.formatDate(new Date(), { dateStyle: DATE_TIME_STYLES.LONG });
+ * ```
+ */
 declare const DATE_TIME_STYLES: {
     readonly FULL: "full";
     readonly LONG: "long";
     readonly MEDIUM: "medium";
     readonly SHORT: "short";
 };
+/**
+ * Represents a date/time formatting style derived from {@link DATE_TIME_STYLES}.
+ */
 type DateTimeStyle = (typeof DATE_TIME_STYLES)[keyof typeof DATE_TIME_STYLES];
+/**
+ * Provides constant values for number formatting styles compatible with the `Intl.NumberFormat` API.
+ *
+ * @example
+ * ```ts
+ * import { NUMBER_FORMAT_STYLES } from "@simplix-react/i18n";
+ *
+ * adapter.formatNumber(1234.5, { style: NUMBER_FORMAT_STYLES.CURRENCY, currency: "USD" });
+ * ```
+ */
 declare const NUMBER_FORMAT_STYLES: {
     readonly DECIMAL: "decimal";
     readonly CURRENCY: "currency";
     readonly PERCENT: "percent";
     readonly UNIT: "unit";
 };
+/**
+ * Represents a number formatting style derived from {@link NUMBER_FORMAT_STYLES}.
+ */
 type NumberFormatStyle = (typeof NUMBER_FORMAT_STYLES)[keyof typeof NUMBER_FORMAT_STYLES];
+/**
+ * Provides constant values for text direction (`"ltr"` or `"rtl"`).
+ */
 declare const TEXT_DIRECTIONS: {
     readonly LTR: "ltr";
     readonly RTL: "rtl";
 };
+/**
+ * Represents a text direction value derived from {@link TEXT_DIRECTIONS}.
+ */
 type TextDirection = (typeof TEXT_DIRECTIONS)[keyof typeof TEXT_DIRECTIONS];
+/**
+ * Defines plural form strings following the CLDR plural rules.
+ *
+ * @see {@link https://cldr.unicode.org/index/cldr-spec/plural-rules | CLDR Plural Rules}
+ */
 interface PluralForms {
     zero?: string;
     one: string;
@@ -30,76 +79,302 @@ interface PluralForms {
     many?: string;
     other: string;
 }
+/**
+ * Configures date/time formatting options passed to `Intl.DateTimeFormat`.
+ */
 interface DateTimeFormatOptions {
+    /** The date formatting style. */
     dateStyle?: DateTimeStyle;
+    /** The time formatting style. */
     timeStyle?: DateTimeStyle;
+    /** Whether to use 12-hour time format. */
     hour12?: boolean;
 }
+/**
+ * Configures number formatting options passed to `Intl.NumberFormat`.
+ */
 interface NumberFormatOptions {
+    /** The number formatting style. */
     style?: NumberFormatStyle;
+    /** ISO 4217 currency code (required when `style` is `"currency"`). */
     currency?: string;
+    /** Unit identifier (required when `style` is `"unit"`). */
     unit?: string;
+    /** Minimum number of fraction digits to display. */
     minimumFractionDigits?: number;
+    /** Maximum number of fraction digits to display. */
     maximumFractionDigits?: number;
 }
+/**
+ * Describes metadata for a single locale including display names, text direction, and default formats.
+ */
 interface LocaleInfo {
+    /** BCP 47 locale code. */
     code: LocaleCode;
+    /** Native name of the locale (e.g., "한국어"). */
     name: string;
+    /** English name of the locale (e.g., "Korean"). */
     englishName: string;
+    /** Text direction for the locale. */
     direction: TextDirection;
+    /** Default date format pattern. */
     dateFormat: string;
+    /** Default time format pattern. */
     timeFormat: string;
+    /** Default ISO 4217 currency code. */
     currency: string;
 }
+/**
+ * Represents a translation namespace identifier used to scope translation keys.
+ */
 type TranslationNamespace = string;
+/**
+ * Provides constant values representing translation resource loading states.
+ */
 declare const TRANSLATION_LOAD_STATES: {
     readonly IDLE: "idle";
     readonly LOADING: "loading";
     readonly LOADED: "loaded";
     readonly ERROR: "error";
 };
+/**
+ * Represents a translation loading state derived from {@link TRANSLATION_LOAD_STATES}.
+ */
 type TranslationLoadState = (typeof TRANSLATION_LOAD_STATES)[keyof typeof TRANSLATION_LOAD_STATES];
 
+/**
+ * Defines the contract for an internationalization adapter.
+ *
+ * Provides translation lookup, locale management, and formatting capabilities.
+ * Implement this interface to integrate a custom i18n backend.
+ *
+ * @see {@link I18nextAdapter} for the built-in i18next implementation.
+ *
+ * @example
+ * ```ts
+ * import type { II18nAdapter } from "@simplix-react/i18n";
+ *
+ * class CustomAdapter implements II18nAdapter {
+ *   // ... implement all required members
+ * }
+ * ```
+ */
 interface II18nAdapter {
+    /** Unique identifier for this adapter implementation. */
     readonly id: string;
+    /** Human-readable name for this adapter. */
     readonly name: string;
+    /** Currently active locale code. */
     readonly locale: LocaleCode;
+    /** Locale code used when a translation key is missing in the active locale. */
     readonly fallbackLocale: LocaleCode;
+    /** List of all locale codes supported by this adapter. */
     readonly availableLocales: LocaleCode[];
+    /**
+     * Initializes the adapter with an optional default locale.
+     * @param defaultLocale - The locale to activate on initialization.
+     */
     initialize(defaultLocale?: LocaleCode): Promise<void>;
+    /** Disposes of the adapter and releases all resources. */
     dispose(): Promise<void>;
+    /**
+     * Changes the active locale.
+     * @param locale - The target locale code.
+     */
     setLocale(locale: LocaleCode): Promise<void>;
+    /**
+     * Returns metadata for the given locale, or `null` if unsupported.
+     * @param locale - The locale code to look up.
+     */
     getLocaleInfo(locale: LocaleCode): LocaleInfo | null;
+    /**
+     * Translates a key with optional interpolation values.
+     * @param key - The translation key.
+     * @param values - Interpolation values.
+     */
     t(key: string, values?: TranslationValues): string;
+    /**
+     * Translates a namespaced key with optional interpolation values.
+     * @param namespace - The translation namespace.
+     * @param key - The translation key within the namespace.
+     * @param values - Interpolation values.
+     */
     tn(namespace: TranslationNamespace, key: string, values?: TranslationValues): string;
+    /**
+     * Translates a key with plural form selection based on count.
+     * @param key - The translation key.
+     * @param count - The count for plural selection.
+     * @param values - Additional interpolation values.
+     */
     tp(key: string, count: number, values?: TranslationValues): string;
+    /**
+     * Checks whether a translation key exists.
+     * @param key - The translation key to check.
+     * @param namespace - Optional namespace to scope the lookup.
+     */
     exists(key: string, namespace?: TranslationNamespace): boolean;
+    /**
+     * Formats a date according to the active locale.
+     * @param date - The date to format.
+     * @param options - Formatting options.
+     */
     formatDate(date: Date, options?: DateTimeFormatOptions): string;
+    /**
+     * Formats a time according to the active locale.
+     * @param date - The date/time to format.
+     * @param options - Formatting options.
+     */
     formatTime(date: Date, options?: DateTimeFormatOptions): string;
+    /**
+     * Formats a date and time together according to the active locale.
+     * @param date - The date/time to format.
+     * @param options - Formatting options.
+     */
     formatDateTime(date: Date, options?: DateTimeFormatOptions): string;
+    /**
+     * Formats a date as a human-readable relative time string (e.g., "3 hours ago").
+     * @param date - The date to compare against the current time.
+     */
     formatRelativeTime(date: Date): string;
+    /**
+     * Formats a number according to the active locale.
+     * @param value - The number to format.
+     * @param options - Formatting options.
+     */
     formatNumber(value: number, options?: NumberFormatOptions): string;
+    /**
+     * Formats a number as a currency string according to the active locale.
+     * @param value - The monetary value to format.
+     * @param currency - ISO 4217 currency code override (defaults to the locale's currency).
+     */
     formatCurrency(value: number, currency?: string): string;
+    /**
+     * Loads translation resources for a given locale and namespace.
+     * @param locale - The target locale code.
+     * @param namespace - The translation namespace.
+     * @param translations - The translation key-value pairs to load.
+     */
     loadTranslations(locale: LocaleCode, namespace: TranslationNamespace, translations: Record<string, string | PluralForms>): void;
+    /**
+     * Returns the loading state of translation resources.
+     * @param locale - The locale to check.
+     * @param namespace - Optional namespace to check (defaults to `"translation"`).
+     */
     getLoadState(locale: LocaleCode, namespace?: TranslationNamespace): TranslationLoadState;
+    /**
+     * Registers a callback invoked whenever the active locale changes.
+     * @param handler - The callback receiving the new locale code.
+     * @returns A function that unregisters the handler when called.
+     */
     onLocaleChange(handler: (locale: LocaleCode) => void): () => void;
 }
 
+/**
+ * Props for the {@link I18nProvider} component.
+ */
 interface I18nProviderProps {
+    /** Child components that will have access to the i18n adapter. */
     children: ReactNode;
+    /** The i18n adapter instance to provide via React context. */
     adapter: II18nAdapter;
 }
+/**
+ * Provides an {@link II18nAdapter} instance to descendant components via React context.
+ *
+ * Wrap your application (or a subtree) with this provider to enable the
+ * {@link useTranslation}, {@link useLocale}, and {@link useI18n} hooks.
+ *
+ * @param props - The provider props.
+ *
+ * @example
+ * ```tsx
+ * import { I18nProvider } from "@simplix-react/i18n/react";
+ * import { createI18nConfig } from "@simplix-react/i18n";
+ *
+ * const { adapter, i18nReady } = createI18nConfig({ defaultLocale: "ko" });
+ * await i18nReady;
+ *
+ * function App() {
+ *   return (
+ *     <I18nProvider adapter={adapter}>
+ *       <MyComponent />
+ *     </I18nProvider>
+ *   );
+ * }
+ * ```
+ */
 declare function I18nProvider({ children, adapter }: I18nProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Returns the {@link II18nAdapter} from the nearest {@link I18nProvider}, or `null` if none exists.
+ *
+ * Prefer {@link useTranslation} or {@link useLocale} for most use cases.
+ * Use this hook when you need direct access to the full adapter API.
+ */
 declare function useI18nAdapter(): II18nAdapter | null;
 
-type TranslateFunction = (key: string, values?: TranslationValues) => string;
-interface UseTranslationReturn {
-    t: TranslateFunction;
+/**
+ * A type-safe translation function that maps keys to translated strings.
+ *
+ * @typeParam TKeys - Union of allowed translation key strings.
+ */
+type TranslateFunction<TKeys extends string = string> = (key: TKeys, values?: TranslationValues) => string;
+/**
+ * Represents the return value of the {@link useTranslation} hook.
+ *
+ * @typeParam TKeys - Union of allowed translation key strings.
+ */
+interface UseTranslationReturn<TKeys extends string = string> {
+    /** Translates a key within the hook's namespace. */
+    t: TranslateFunction<TKeys>;
+    /** The currently active locale code. */
     locale: LocaleCode;
+    /** Checks whether a translation key exists in the hook's namespace. */
     exists: (key: string) => boolean;
 }
-declare function useTranslation(namespace: string): UseTranslationReturn;
+/**
+ * Provides namespace-scoped translation capabilities with automatic re-rendering on locale changes.
+ *
+ * Uses `useSyncExternalStore` to subscribe to locale changes from the adapter,
+ * ensuring consistent rendering during concurrent React features.
+ *
+ * @typeParam TKeys - Union of allowed translation key strings for type-safe lookups.
+ * @param namespace - The translation namespace to scope all lookups to.
+ * @returns A {@link UseTranslationReturn} object with `t`, `locale`, and `exists`.
+ *
+ * @example
+ * ```tsx
+ * import { useTranslation } from "@simplix-react/i18n/react";
+ *
+ * function Greeting() {
+ *   const { t, locale } = useTranslation("common");
+ *   return <p>{t("greeting")} (locale: {locale})</p>;
+ * }
+ * ```
+ */
+declare function useTranslation<TKeys extends string = string>(namespace: string): UseTranslationReturn<TKeys>;
+/**
+ * Returns the {@link II18nAdapter} from context for direct adapter access.
+ *
+ * Shorthand for {@link useI18nAdapter}. Use {@link useTranslation} for namespace-scoped translations.
+ */
 declare function useI18n(): II18nAdapter | null;
+/**
+ * Returns the currently active locale code and re-renders on locale changes.
+ *
+ * Uses `useSyncExternalStore` to subscribe to locale changes from the adapter.
+ *
+ * @returns The active {@link LocaleCode}.
+ *
+ * @example
+ * ```tsx
+ * import { useLocale } from "@simplix-react/i18n/react";
+ *
+ * function LocaleDisplay() {
+ *   const locale = useLocale();
+ *   return <span>Current: {locale}</span>;
+ * }
+ * ```
+ */
 declare function useLocale(): LocaleCode;
 
 export { I18nProvider, type I18nProviderProps, type TranslateFunction, type UseTranslationReturn, useI18n, useI18nAdapter, useLocale, useTranslation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplix-react/i18n",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Internationalization framework with i18next adapter",
   "type": "module",
   "exports": {
@@ -13,7 +13,12 @@
       "import": "./dist/react.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
@@ -28,11 +33,18 @@
     "react-i18next": ">=16.0.0"
   },
   "peerDependenciesMeta": {
-    "i18next": { "optional": true },
-    "react": { "optional": true },
-    "react-i18next": { "optional": true }
+    "i18next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-i18next": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@simplix-react/config-eslint": "workspace:*",
     "@simplix-react/config-typescript": "workspace:*",
     "@types/react": "^19.0.0",
     "eslint": "^9.39.2",