inline-i18n-multi 0.4.0 → 0.6.0

package/README.md

@@ -59,6 +59,14 @@ See "Hello" in your app? Just search for "Hello" in your codebase. **Done.**
 - **Missing Translation Warning** - Development-time diagnostics with customizable handlers
 - **Namespace Support** - Organize translations for large apps (`t('common:greeting')`)
 - **Debug Mode** - Visual indicators for missing/fallback translations
+- **Currency Formatting** - Locale-aware currency display (`{price, currency, USD}`)
+- **Compact Number Formatting** - Short number display (`{count, number, compact}`)
+- **Rich Text Interpolation** - Embed React components in translations (`<link>text</link>`)
+- **Lazy Loading** - Async dictionary loading on demand (`loadAsync()`)
+- **Custom Formatter Registry** - Register custom ICU-style formatters (`registerFormatter('phone', fn)`)
+- **Interpolation Guards** - Handle missing variables gracefully (`missingVarHandler`)
+- **Locale Detection** - Auto-detect user locale from navigator, cookie, URL, or header (`detectLocale()`)
+- **Selectordinal** - Ordinal plural formatting (`{rank, selectordinal, one {#st} two {#nd} ...}`)
 
 ---
 
@@ -202,8 +210,11 @@ it({
 }, { price: 1234.56 })  // → "Price: 1,234.56"
 ```
 
-**Supported ICU styles:**
-- `number`: `decimal`, `percent`, `integer`, `currency`
+**Supported ICU types:**
+- `plural`: `zero`, `one`, `two`, `few`, `many`, `other` (and exact matches like `=0`, `=1`)
+- `select`: match on string values
+- `selectordinal`: ordinal plural categories (`one`, `two`, `few`, `other`)
+- `number`: `decimal`, `percent`, `integer`, `currency`, `compact`, `compactLong`
 - `date`: `short`, `medium`, `long`, `full`
 - `time`: `short`, `medium`, `long`, `full`
 
@@ -234,6 +245,33 @@ it({ en: '{options, list, disjunction}' }, { options: ['A', 'B'] })
 // → "A or B"
 ```
 
+### Currency Formatting
+
+```typescript
+it({
+  en: 'Total: {price, currency, USD}',
+  ko: '합계: {price, currency, KRW}'
+}, { price: 42000 })
+// en → "Total: $42,000.00"  /  ko → "합계: ₩42,000"
+
+// Defaults to USD when currency code omitted
+it({ en: '{price, currency}' }, { price: 100 })
+// → "$100.00"
+```
+
+### Compact Number Formatting
+
+```typescript
+it({
+  en: '{count, number, compact} views',
+  ko: '{count, number, compact} 조회'
+}, { count: 1500000 })
+// en → "1.5M views"  /  ko → "150만 조회"
+
+it({ en: '{count, number, compactLong}' }, { count: 1500000 })
+// → "1.5 million"
+```
+
 ---
 
 ## Namespace Support
@@ -278,6 +316,241 @@ t('missing.key')  // → "[MISSING: fr] missing.key"
 
 ---
 
+## Rich Text Interpolation
+
+Embed React components within translations:
+
+```tsx
+import { RichText, useRichText } from 'inline-i18n-multi-react'
+
+// Component syntax
+<RichText
+  translations={{
+    en: 'Read <link>terms</link> and <bold>agree</bold>',
+    ko: '<link>약관</link>을 읽고 <bold>동의</bold>해주세요'
+  }}
+  components={{
+    link: (text) => <a href="/terms">{text}</a>,
+    bold: (text) => <strong>{text}</strong>
+  }}
+/>
+
+// Hook syntax
+const richT = useRichText({
+  link: (text) => <a href="/terms">{text}</a>,
+  bold: (text) => <strong>{text}</strong>
+})
+richT({ en: 'Click <link>here</link>', ko: '<link>여기</link> 클릭' })
+```
+
+---
+
+## Lazy Loading
+
+Load dictionaries asynchronously on demand:
+
+```typescript
+import { configure, loadAsync, isLoaded, t } from 'inline-i18n-multi'
+
+configure({
+  loader: (locale, namespace) => import(`./locales/${locale}/${namespace}.json`)
+})
+
+await loadAsync('ko', 'dashboard')
+t('dashboard:title')
+
+isLoaded('ko', 'dashboard')  // → true
+```
+
+### React Hook
+
+```tsx
+import { useLoadDictionaries } from 'inline-i18n-multi-react'
+
+function Dashboard() {
+  const { isLoading, error } = useLoadDictionaries('ko', 'dashboard')
+  if (isLoading) return <Spinner />
+  if (error) return <Error message={error.message} />
+  return <Content />
+}
+```
+
+---
+
+## Custom Formatter Registry
+
+Register custom ICU-style formatters for domain-specific formatting:
+
+```typescript
+import { registerFormatter, clearFormatters, it, setLocale } from 'inline-i18n-multi'
+
+setLocale('en')
+
+// Register a phone number formatter
+registerFormatter('phone', (value, locale, style?) => {
+  const s = String(value)
+  if (locale === 'ko') return `${s.slice(0, 3)}-${s.slice(3, 7)}-${s.slice(7)}`
+  return `(${s.slice(0, 3)}) ${s.slice(3, 6)}-${s.slice(6)}`
+})
+
+// Use in translations
+it({
+  en: 'Call {num, phone}',
+  ko: '전화: {num, phone}'
+}, { num: '2125551234' })
+// → "Call (212) 555-1234"
+
+// Register a formatter with style support
+registerFormatter('mask', (value, locale, style?) => {
+  const s = String(value)
+  if (style === 'email') {
+    const [user, domain] = s.split('@')
+    return `${user[0]}***@${domain}`
+  }
+  return s.slice(0, 2) + '***' + s.slice(-2)
+})
+
+it({ en: 'Email: {email, mask, email}' }, { email: 'john@example.com' })
+// → "Email: j***@example.com"
+
+// Clear all custom formatters
+clearFormatters()
+```
+
+Reserved names (`plural`, `select`, `selectordinal`, `number`, `date`, `time`, `relativeTime`, `list`, `currency`) cannot be used as custom formatter names and will throw an error.
+
+---
+
+## Interpolation Guards
+
+Handle missing interpolation variables gracefully with a custom handler:
+
+```typescript
+import { configure, it, setLocale } from 'inline-i18n-multi'
+
+setLocale('en')
+
+// Configure a missing variable handler
+configure({
+  missingVarHandler: (varName, locale) => {
+    console.warn(`Missing variable "${varName}" for locale "${locale}"`)
+    return `[${varName}]`
+  }
+})
+
+// When a variable is missing, the handler is called instead of leaving {varName}
+it({ en: 'Hello, {name}!' })
+// logs: Missing variable "name" for locale "en"
+// → "Hello, [name]!"
+
+// Works with ICU patterns too
+it({ en: '{count, plural, one {# item} other {# items}}' })
+// logs: Missing variable "count" for locale "en"
+// → "{count}"
+
+// Without a handler, missing variables are left as-is: {varName}
+```
+
+---
+
+## Locale Detection
+
+Auto-detect the user's locale from multiple sources:
+
+```typescript
+import { detectLocale, setLocale } from 'inline-i18n-multi'
+
+// Basic detection from browser navigator
+const locale = detectLocale({
+  supportedLocales: ['en', 'ko', 'ja'],
+  defaultLocale: 'en',
+})
+setLocale(locale)
+
+// Multiple sources in priority order
+const detected = detectLocale({
+  supportedLocales: ['en', 'ko', 'ja'],
+  defaultLocale: 'en',
+  sources: ['cookie', 'url', 'navigator'],
+  cookieName: 'NEXT_LOCALE',  // default
+})
+
+// Server-side detection from Accept-Language header
+const ssrLocale = detectLocale({
+  supportedLocales: ['en', 'ko', 'ja'],
+  defaultLocale: 'en',
+  sources: ['header'],
+  headerValue: 'ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7',
+})
+// → "ko"
+
+// BCP 47 parent matching (en-US matches en)
+const matched = detectLocale({
+  supportedLocales: ['en', 'ko'],
+  defaultLocale: 'en',
+  sources: ['navigator'],
+})
+// Browser reports "en-US" → matches "en"
+```
+
+**Detection sources:**
+
+| Source | Description |
+|--------|-------------|
+| `navigator` | Browser `navigator.languages` / `navigator.language` |
+| `cookie` | Reads locale from `document.cookie` (configurable name) |
+| `url` | First path segment (e.g., `/ko/about` matches `ko`) |
+| `header` | Parses `Accept-Language` header value (for SSR) |
+
+Sources are tried in order; the first match wins. If no source matches, `defaultLocale` is returned.
+
+---
+
+## Selectordinal
+
+Ordinal plural formatting for ranking and ordering (e.g., 1st, 2nd, 3rd):
+
+```typescript
+import { it, setLocale } from 'inline-i18n-multi'
+
+setLocale('en')
+
+// Ordinal suffixes
+it({
+  en: '{rank, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}'
+}, { rank: 1 })   // → "1st"
+
+it({
+  en: '{rank, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}'
+}, { rank: 2 })   // → "2nd"
+
+it({
+  en: '{rank, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}'
+}, { rank: 3 })   // → "3rd"
+
+it({
+  en: '{rank, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}'
+}, { rank: 4 })   // → "4th"
+
+// Handles English irregulars correctly
+it({
+  en: '{rank, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}'
+}, { rank: 11 })  // → "11th" (not "11st")
+
+it({
+  en: '{rank, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}'
+}, { rank: 21 })  // → "21st"
+
+// Combined with text
+it({
+  en: 'You finished {rank, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} place!'
+}, { rank: 3 })   // → "You finished 3rd place!"
+```
+
+Uses `Intl.PluralRules` with `{ type: 'ordinal' }` for locale-aware ordinal categories.
+
+---
+
 ## Configuration
 
 Configure global settings for fallback behavior and warnings:
@@ -363,9 +636,33 @@ Available helpers:
 
 | Function | Description |
 |----------|-------------|
-| `configure(options)` | Configure global settings (fallback, warnings, debug) |
+| `configure(options)` | Configure global settings (fallback, warnings, debug, missingVarHandler) |
 | `getConfig()` | Get current configuration |
 | `resetConfig()` | Reset configuration to defaults |
+| `loadAsync(locale, namespace?)` | Asynchronously load dictionary using configured loader |
+| `isLoaded(locale, namespace?)` | Check if dictionary has been loaded |
+| `parseRichText(template, names)` | Parse rich text template into segments |
+
+### Custom Formatters
+
+| Function | Description |
+|----------|-------------|
+| `registerFormatter(name, formatter)` | Register a custom ICU-style formatter |
+| `clearFormatters()` | Clear all custom formatters |
+
+### Locale Detection
+
+| Function | Description |
+|----------|-------------|
+| `detectLocale(options)` | Auto-detect user's locale from multiple sources |
+
+### React Hooks & Components
+
+| Export | Description |
+|--------|-------------|
+| `RichText` | Rich text translation component with embedded components |
+| `useRichText(components)` | Hook returning function for rich text translations |
+| `useLoadDictionaries(locale, ns?)` | Hook for lazy loading dictionaries with loading state |
 
 ### Types
 
@@ -382,6 +679,8 @@ interface Config {
   warnOnMissing?: boolean
   onMissingTranslation?: WarningHandler
   debugMode?: boolean | DebugModeOptions
+  loader?: (locale: Locale, namespace: string) => Promise<Record<string, unknown>>
+  missingVarHandler?: (varName: string, locale: string) => string
 }
 
 interface DebugModeOptions {
@@ -400,6 +699,29 @@ interface TranslationWarning {
 }
 
 type WarningHandler = (warning: TranslationWarning) => void
+
+type CustomFormatter = (value: unknown, locale: string, style?: string) => string
+
+type DetectSource = 'navigator' | 'cookie' | 'url' | 'header'
+
+interface DetectLocaleOptions {
+  /** Locales your app supports */
+  supportedLocales: Locale[]
+  /** Fallback when no source matches */
+  defaultLocale: Locale
+  /** Detection sources in priority order (default: ['navigator']) */
+  sources?: DetectSource[]
+  /** Cookie name to read (default: 'NEXT_LOCALE') */
+  cookieName?: string
+  /** Accept-Language header value (for SSR) */
+  headerValue?: string
+}
+
+interface RichTextSegment {
+  type: 'text' | 'component'
+  content: string
+  componentName?: string
+}
 ```
 
 ---
@@ -454,30 +776,6 @@ npm install inline-i18n-multi-next
 
 ---
 
-## Build-Time Optimization
-
-### Babel Plugin
-
-Transform `it()` calls at build time for better performance. Extracts translations for static analysis and enables dead code elimination for unused locales.
-
-```bash
-npm install -D @inline-i18n-multi/babel-plugin
-```
-
-[View Babel plugin →](https://www.npmjs.com/package/@inline-i18n-multi/babel-plugin)
-
-### SWC Plugin
-
-SWC plugin for Next.js 13+ projects. Faster than Babel with the same optimization benefits. Configure in `next.config.js` under `experimental.swcPlugins`.
-
-```bash
-npm install -D @inline-i18n-multi/swc-plugin
-```
-
-[View SWC plugin →](https://www.npmjs.com/package/@inline-i18n-multi/swc-plugin)
-
----
-
 ## Developer Tools
 
 ### CLI
@@ -504,7 +802,6 @@ npm install -D @inline-i18n-multi/cli
 **Please read the [full documentation on GitHub](https://github.com/exiivy98/inline-i18n-multi)** for:
 - Complete API reference
 - Framework integrations (React, Next.js)
-- Build-time optimization
 - CLI tools
 - Best practices and examples
 

package/dist/index.d.mts

@@ -61,6 +61,10 @@ interface Config {
     onMissingTranslation?: WarningHandler;
     /** Enable debug mode with visual indicators (default: false) */
     debugMode?: boolean | DebugModeOptions;
+    /** Async loader function for lazy loading dictionaries */
+    loader?: (locale: Locale, namespace: string) => Promise<Record<string, unknown>>;
+    /** Custom handler for missing interpolation variables (v0.6.0) */
+    missingVarHandler?: (varName: string, locale: string) => string;
 }
 
 /**
@@ -81,10 +85,9 @@ declare function setLocale(locale: Locale): void;
 declare function getLocale(): Locale;
 
 /**
- * Runtime lookup function for plugin-transformed code.
- * This is called by code that has been processed by @inline-i18n-multi/babel-plugin
- * or @inline-i18n-multi/swc-plugin.
+ * Runtime lookup function for build-tool-transformed code.
  *
+ * @deprecated Will be removed in v1.0.0
  * @param _hash - Content hash (for caching/debugging, unused at runtime)
  * @param translations - Translation map with locale keys
  * @param vars - Variables for interpolation
@@ -158,6 +161,24 @@ declare function loadDictionary(locale: Locale, dict: Dictionary, namespace?: st
  * @param namespace - Optional namespace to clear (clears all if not specified)
  */
 declare function clearDictionaries(namespace?: string): void;
+/**
+ * Asynchronously load a dictionary using the configured loader
+ * @param locale - Locale to load
+ * @param namespace - Optional namespace (defaults to 'default')
+ * @throws Error if no loader is configured
+ *
+ * @example
+ * configure({ loader: (locale, ns) => import(`./locales/${locale}/${ns}.json`) })
+ * await loadAsync('ko', 'dashboard')
+ * t('dashboard:title')
+ */
+declare function loadAsync(locale: Locale, namespace?: string): Promise<void>;
+/**
+ * Check if a dictionary has been loaded for a locale/namespace
+ * @param locale - Locale to check
+ * @param namespace - Optional namespace (defaults to 'default')
+ */
+declare function isLoaded(locale: Locale, namespace?: string): boolean;
 /**
  * Translate using key-based lookup (i18n compatible)
  * @param key - Dot-separated translation key, optionally prefixed with namespace
@@ -191,6 +212,7 @@ declare function getDictionary(locale: Locale, namespace?: string): Dictionary |
  */
 declare function getLoadedNamespaces(): string[];
 
+type FullConfig = Required<Omit<Config, 'loader' | 'missingVarHandler'>> & Pick<Config, 'loader' | 'missingVarHandler'>;
 /**
  * Configure inline-i18n-multi settings
  *
@@ -205,10 +227,80 @@ declare function configure(options: Partial<Config>): void;
 /**
  * Get current configuration
  */
-declare function getConfig(): Required<Config>;
+declare function getConfig(): FullConfig;
 /**
  * Reset configuration to defaults
  */
 declare function resetConfig(): void;
 
-export { type Config, type DebugModeOptions, type Dictionaries, type Dictionary, type Locale, type PluralRules, type TranslationVars, type TranslationWarning, type Translations, type WarningHandler, __i18n_lookup, clearDictionaries, configure, en_de, en_es, en_fr, en_ja, en_zh, getConfig, getDictionary, getLoadedLocales, getLoadedNamespaces, getLocale, hasTranslation, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadDictionaries, loadDictionary, resetConfig, setLocale, t, zh_es };
+type CustomFormatter = (value: unknown, locale: string, style?: string) => string;
+/**
+ * Register a custom formatter
+ *
+ * @example
+ * registerFormatter('phone', (value, locale, style?) => {
+ *   const s = String(value)
+ *   return `(${s.slice(0,3)}) ${s.slice(3,6)}-${s.slice(6)}`
+ * })
+ */
+declare function registerFormatter(name: string, formatter: CustomFormatter): void;
+/**
+ * Clear all custom formatters
+ */
+declare function clearFormatters(): void;
+
+type DetectSource = 'navigator' | 'cookie' | 'url' | 'header';
+interface DetectLocaleOptions {
+    /** Locales your app supports */
+    supportedLocales: Locale[];
+    /** Fallback when no source matches */
+    defaultLocale: Locale;
+    /** Detection sources in priority order (default: ['navigator']) */
+    sources?: DetectSource[];
+    /** Cookie name to read (default: 'NEXT_LOCALE') */
+    cookieName?: string;
+    /** Accept-Language header value (for SSR) */
+    headerValue?: string;
+}
+/**
+ * Auto-detect the user's locale from multiple sources
+ *
+ * @example
+ * const locale = detectLocale({
+ *   supportedLocales: ['en', 'ko', 'ja'],
+ *   defaultLocale: 'en',
+ *   sources: ['cookie', 'navigator'],
+ *   cookieName: 'NEXT_LOCALE',
+ * })
+ */
+declare function detectLocale(options: DetectLocaleOptions): Locale;
+
+/**
+ * Rich Text segment types
+ */
+interface RichTextSegment {
+    type: 'text' | 'component';
+    content: string;
+    /** Component name (only for type === 'component') */
+    componentName?: string;
+}
+/**
+ * Parse a template string into rich text segments.
+ * Matches patterns like <name>content</name> for each component name.
+ *
+ * @param template - The template string with component tags
+ * @param componentNames - Array of valid component names to match
+ * @returns Array of segments (text or component)
+ *
+ * @example
+ * parseRichText('Read <link>terms</link> and <bold>agree</bold>', ['link', 'bold'])
+ * // [
+ * //   { type: 'text', content: 'Read ' },
+ * //   { type: 'component', content: 'terms', componentName: 'link' },
+ * //   { type: 'text', content: ' and ' },
+ * //   { type: 'component', content: 'agree', componentName: 'bold' },
+ * // ]
+ */
+declare function parseRichText(template: string, componentNames: string[]): RichTextSegment[];
+
+export { type Config, type CustomFormatter, type DebugModeOptions, type DetectLocaleOptions, type DetectSource, type Dictionaries, type Dictionary, type Locale, type PluralRules, type RichTextSegment, type TranslationVars, type TranslationWarning, type Translations, type WarningHandler, __i18n_lookup, clearDictionaries, clearFormatters, configure, detectLocale, en_de, en_es, en_fr, en_ja, en_zh, getConfig, getDictionary, getLoadedLocales, getLoadedNamespaces, getLocale, hasTranslation, isLoaded, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadAsync, loadDictionaries, loadDictionary, parseRichText, registerFormatter, resetConfig, setLocale, t, zh_es };

package/dist/index.d.ts

@@ -61,6 +61,10 @@ interface Config {
     onMissingTranslation?: WarningHandler;
     /** Enable debug mode with visual indicators (default: false) */
     debugMode?: boolean | DebugModeOptions;
+    /** Async loader function for lazy loading dictionaries */
+    loader?: (locale: Locale, namespace: string) => Promise<Record<string, unknown>>;
+    /** Custom handler for missing interpolation variables (v0.6.0) */
+    missingVarHandler?: (varName: string, locale: string) => string;
 }
 
 /**
@@ -81,10 +85,9 @@ declare function setLocale(locale: Locale): void;
 declare function getLocale(): Locale;
 
 /**
- * Runtime lookup function for plugin-transformed code.
- * This is called by code that has been processed by @inline-i18n-multi/babel-plugin
- * or @inline-i18n-multi/swc-plugin.
+ * Runtime lookup function for build-tool-transformed code.
  *
+ * @deprecated Will be removed in v1.0.0
  * @param _hash - Content hash (for caching/debugging, unused at runtime)
  * @param translations - Translation map with locale keys
  * @param vars - Variables for interpolation
@@ -158,6 +161,24 @@ declare function loadDictionary(locale: Locale, dict: Dictionary, namespace?: st
  * @param namespace - Optional namespace to clear (clears all if not specified)
  */
 declare function clearDictionaries(namespace?: string): void;
+/**
+ * Asynchronously load a dictionary using the configured loader
+ * @param locale - Locale to load
+ * @param namespace - Optional namespace (defaults to 'default')
+ * @throws Error if no loader is configured
+ *
+ * @example
+ * configure({ loader: (locale, ns) => import(`./locales/${locale}/${ns}.json`) })
+ * await loadAsync('ko', 'dashboard')
+ * t('dashboard:title')
+ */
+declare function loadAsync(locale: Locale, namespace?: string): Promise<void>;
+/**
+ * Check if a dictionary has been loaded for a locale/namespace
+ * @param locale - Locale to check
+ * @param namespace - Optional namespace (defaults to 'default')
+ */
+declare function isLoaded(locale: Locale, namespace?: string): boolean;
 /**
  * Translate using key-based lookup (i18n compatible)
  * @param key - Dot-separated translation key, optionally prefixed with namespace
@@ -191,6 +212,7 @@ declare function getDictionary(locale: Locale, namespace?: string): Dictionary |
  */
 declare function getLoadedNamespaces(): string[];
 
+type FullConfig = Required<Omit<Config, 'loader' | 'missingVarHandler'>> & Pick<Config, 'loader' | 'missingVarHandler'>;
 /**
  * Configure inline-i18n-multi settings
  *
@@ -205,10 +227,80 @@ declare function configure(options: Partial<Config>): void;
 /**
  * Get current configuration
  */
-declare function getConfig(): Required<Config>;
+declare function getConfig(): FullConfig;
 /**
  * Reset configuration to defaults
  */
 declare function resetConfig(): void;
 
-export { type Config, type DebugModeOptions, type Dictionaries, type Dictionary, type Locale, type PluralRules, type TranslationVars, type TranslationWarning, type Translations, type WarningHandler, __i18n_lookup, clearDictionaries, configure, en_de, en_es, en_fr, en_ja, en_zh, getConfig, getDictionary, getLoadedLocales, getLoadedNamespaces, getLocale, hasTranslation, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadDictionaries, loadDictionary, resetConfig, setLocale, t, zh_es };
+type CustomFormatter = (value: unknown, locale: string, style?: string) => string;
+/**
+ * Register a custom formatter
+ *
+ * @example
+ * registerFormatter('phone', (value, locale, style?) => {
+ *   const s = String(value)
+ *   return `(${s.slice(0,3)}) ${s.slice(3,6)}-${s.slice(6)}`
+ * })
+ */
+declare function registerFormatter(name: string, formatter: CustomFormatter): void;
+/**
+ * Clear all custom formatters
+ */
+declare function clearFormatters(): void;
+
+type DetectSource = 'navigator' | 'cookie' | 'url' | 'header';
+interface DetectLocaleOptions {
+    /** Locales your app supports */
+    supportedLocales: Locale[];
+    /** Fallback when no source matches */
+    defaultLocale: Locale;
+    /** Detection sources in priority order (default: ['navigator']) */
+    sources?: DetectSource[];
+    /** Cookie name to read (default: 'NEXT_LOCALE') */
+    cookieName?: string;
+    /** Accept-Language header value (for SSR) */
+    headerValue?: string;
+}
+/**
+ * Auto-detect the user's locale from multiple sources
+ *
+ * @example
+ * const locale = detectLocale({
+ *   supportedLocales: ['en', 'ko', 'ja'],
+ *   defaultLocale: 'en',
+ *   sources: ['cookie', 'navigator'],
+ *   cookieName: 'NEXT_LOCALE',
+ * })
+ */
+declare function detectLocale(options: DetectLocaleOptions): Locale;
+
+/**
+ * Rich Text segment types
+ */
+interface RichTextSegment {
+    type: 'text' | 'component';
+    content: string;
+    /** Component name (only for type === 'component') */
+    componentName?: string;
+}
+/**
+ * Parse a template string into rich text segments.
+ * Matches patterns like <name>content</name> for each component name.
+ *
+ * @param template - The template string with component tags
+ * @param componentNames - Array of valid component names to match
+ * @returns Array of segments (text or component)
+ *
+ * @example
+ * parseRichText('Read <link>terms</link> and <bold>agree</bold>', ['link', 'bold'])
+ * // [
+ * //   { type: 'text', content: 'Read ' },
+ * //   { type: 'component', content: 'terms', componentName: 'link' },
+ * //   { type: 'text', content: ' and ' },
+ * //   { type: 'component', content: 'agree', componentName: 'bold' },
+ * // ]
+ */
+declare function parseRichText(template: string, componentNames: string[]): RichTextSegment[];
+
+export { type Config, type CustomFormatter, type DebugModeOptions, type DetectLocaleOptions, type DetectSource, type Dictionaries, type Dictionary, type Locale, type PluralRules, type RichTextSegment, type TranslationVars, type TranslationWarning, type Translations, type WarningHandler, __i18n_lookup, clearDictionaries, clearFormatters, configure, detectLocale, en_de, en_es, en_fr, en_ja, en_zh, getConfig, getDictionary, getLoadedLocales, getLoadedNamespaces, getLocale, hasTranslation, isLoaded, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadAsync, loadDictionaries, loadDictionary, parseRichText, registerFormatter, resetConfig, setLocale, t, zh_es };