inline-i18n-multi-next 0.5.0 → 0.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 # inline-i18n-multi-next
 
-Next.js App Router integration for inline-i18n-multi. Full SSR/SSG support with SEO utilities.
+Next.js App Router integration for inline-i18n-multi. Full SSR/SSG support with SEO utilities, rich text, locale detection, and i18n middleware.
 
 ## Installation
 
@@ -10,6 +10,13 @@ Next.js App Router integration for inline-i18n-multi. Full SSR/SSG support with
 npm install inline-i18n-multi-next
 ```
 
+## Entry Points
+
+| Entry point | Environment | Key exports |
+|---|---|---|
+| `inline-i18n-multi-next/server` | Server Components | `it`, `t`, `configureI18n`, `generateLocaleParams`, `createMetadata`, `getAlternates`, `createI18nMiddleware` |
+| `inline-i18n-multi-next/client` | Client Components | `LocaleProvider`, `useLocale`, `useT`, `it`, `T`, `RichText`, `useRichText`, `useLoadDictionaries`, `useDetectedLocale`, `registerFormatter`, `clearFormatters`, `detectLocale`, `clearICUCache`, `restoreLocale`, `configure`, `resetConfig` |
+
 ## Quick Start
 
 ### Layout Setup
@@ -88,6 +95,122 @@ export function ClientComponent() {
 }
 ```
 
+## Rich Text (Client Components)
+
+Use `RichText` or `useRichText` to embed React components inside translated strings. Tags like `<link>text</link>` are mapped to component renderers.
+
+### RichText Component
+
+```tsx
+'use client'
+import { RichText } from 'inline-i18n-multi-next/client'
+
+export function TermsNotice() {
+  return (
+    <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>,
+      }}
+    />
+  )
+}
+```
+
+### useRichText Hook
+
+```tsx
+'use client'
+import { useRichText } from 'inline-i18n-multi-next/client'
+
+export function RichContent() {
+  const richT = useRichText({
+    link: (text) => <a href="/terms">{text}</a>,
+    bold: (text) => <strong>{text}</strong>,
+  })
+
+  return <p>{richT({ en: 'Click <link>here</link>', ko: '<link>여기</link> 클릭' })}</p>
+}
+```
+
+## Lazy Loading (Client Components)
+
+Use `useLoadDictionaries` to load translations on demand in client components.
+
+```tsx
+'use client'
+import { useLoadDictionaries, useT } from 'inline-i18n-multi-next/client'
+import { useLocale } from 'inline-i18n-multi-next/client'
+
+export function LazySection() {
+  const locale = useLocale()
+  const { isLoading, error } = useLoadDictionaries(locale, 'dashboard')
+  const t = useT()
+
+  if (isLoading) return <p>Loading...</p>
+  if (error) return <p>Failed to load translations</p>
+
+  return <h2>{t('dashboard.title')}</h2>
+}
+```
+
+## Locale Detection
+
+### Client-Side: useDetectedLocale
+
+Automatically detect and set the user's locale from browser signals (navigator, cookie, URL).
+
+```tsx
+'use client'
+import { useDetectedLocale } from 'inline-i18n-multi-next/client'
+
+export function LocaleDetector() {
+  useDetectedLocale({
+    supportedLocales: ['en', 'ko', 'ja'],
+    defaultLocale: 'en',
+    sources: ['cookie', 'navigator'],
+    cookieName: 'NEXT_LOCALE',
+  })
+
+  return null // detection runs on mount, updates context automatically
+}
+```
+
+Detection sources (checked in order):
+
+| Source | Description |
+|---|---|
+| `'navigator'` | Browser `navigator.languages` |
+| `'cookie'` | Read from `document.cookie` |
+| `'url'` | First path segment (e.g., `/ko/about`) |
+| `'header'` | `Accept-Language` header (SSR) |
+
+### Server-Side: createI18nMiddleware
+
+Redirect users to locale-prefixed routes based on cookies or `Accept-Language` header.
+
+```ts
+// middleware.ts
+import { createI18nMiddleware } from 'inline-i18n-multi-next/server'
+
+export default createI18nMiddleware({
+  locales: ['en', 'ko', 'ja'],
+  defaultLocale: 'en',
+  localeDetection: true,   // detect from Accept-Language (default: true)
+  cookieName: 'NEXT_LOCALE', // cookie for user preference (default: 'NEXT_LOCALE')
+})
+
+export const config = {
+  matcher: ['/((?!api|_next|.*\\..*).*)'],
+}
+```
+
+The middleware checks in order: URL locale prefix, cookie preference, then `Accept-Language` header. If no locale prefix is found, it redirects to the detected locale path.
+
 ## SEO Utilities
 
 ```tsx
@@ -106,6 +229,56 @@ export async function generateMetadata({ params }) {
 }
 ```
 
+## Plural Shorthand (v0.7.0)
+
+Concise plural syntax:
+
+```tsx
+// Server Component
+export default async function Page() {
+  return (
+    <p>
+      {await it({
+        en: '{count, p, item|items}',
+        ko: '{count}개',
+      }, { count: 5 })}
+    </p>
+  )
+}
+
+// Client Component - also supports 3-part (zero|singular|plural)
+<T en="{count, p, no items|item|items}" ko="{count, p, 없음|개|개}" count={0} />
+```
+
+## Locale Persistence (v0.7.0)
+
+Auto-save and restore locale:
+
+```tsx
+'use client'
+import { configure, restoreLocale } from 'inline-i18n-multi-next/client'
+
+configure({
+  persistLocale: { storage: 'cookie', key: 'LOCALE', expires: 365 }
+})
+
+// Restore on app init
+const saved = restoreLocale() // returns locale string or undefined
+```
+
+## Custom Formatters
+
+Register custom ICU formatters via the core re-exports.
+
+```tsx
+'use client'
+import { registerFormatter, clearFormatters } from 'inline-i18n-multi-next/client'
+
+registerFormatter('uppercase', (value) => String(value).toUpperCase())
+
+// Use in translations: {name, uppercase}
+```
+
 ## Documentation
 
 **Please read the [full documentation on GitHub](https://github.com/exiivy98/inline-i18n-multi)** for complete API reference, SEO best practices, and advanced patterns.

package/dist/client.d.mts

@@ -1 +1 @@
-export { Dictionaries, Dictionary, Locale, LocaleProvider, PluralRules, RichText, RichTextSegment, T, TranslationVars, Translations, clearDictionaries, en_de, en_es, en_fr, en_ja, en_zh, getDictionary, getLoadedLocales, getLocale, hasTranslation, isLoaded, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadAsync, loadDictionaries, loadDictionary, parseRichText, setLocale, t, useLoadDictionaries, useLocale, useRichText, useT, zh_es } from 'inline-i18n-multi-react';
+export { CustomFormatter, DetectLocaleOptions, DetectSource, Dictionaries, Dictionary, Locale, LocaleProvider, PluralRules, RichText, RichTextSegment, T, TranslationVars, Translations, clearDictionaries, clearFormatters, clearICUCache, detectLocale, en_de, en_es, en_fr, en_ja, en_zh, getDictionary, getLoadedLocales, getLocale, hasTranslation, isLoaded, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadAsync, loadDictionaries, loadDictionary, parseRichText, registerFormatter, restoreLocale, setLocale, t, useDetectedLocale, useLoadDictionaries, useLocale, useRichText, useT, zh_es } from 'inline-i18n-multi-react';

package/dist/client.d.ts

@@ -1 +1 @@
-export { Dictionaries, Dictionary, Locale, LocaleProvider, PluralRules, RichText, RichTextSegment, T, TranslationVars, Translations, clearDictionaries, en_de, en_es, en_fr, en_ja, en_zh, getDictionary, getLoadedLocales, getLocale, hasTranslation, isLoaded, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadAsync, loadDictionaries, loadDictionary, parseRichText, setLocale, t, useLoadDictionaries, useLocale, useRichText, useT, zh_es } from 'inline-i18n-multi-react';
+export { CustomFormatter, DetectLocaleOptions, DetectSource, Dictionaries, Dictionary, Locale, LocaleProvider, PluralRules, RichText, RichTextSegment, T, TranslationVars, Translations, clearDictionaries, clearFormatters, clearICUCache, detectLocale, en_de, en_es, en_fr, en_ja, en_zh, getDictionary, getLoadedLocales, getLocale, hasTranslation, isLoaded, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadAsync, loadDictionaries, loadDictionary, parseRichText, registerFormatter, restoreLocale, setLocale, t, useDetectedLocale, useLoadDictionaries, useLocale, useRichText, useT, zh_es } from 'inline-i18n-multi-react';

package/dist/client.js

@@ -20,6 +20,18 @@ Object.defineProperty(exports, "clearDictionaries", {
   enumerable: true,
   get: function () { return inlineI18nMultiReact.clearDictionaries; }
 });
+Object.defineProperty(exports, "clearFormatters", {
+  enumerable: true,
+  get: function () { return inlineI18nMultiReact.clearFormatters; }
+});
+Object.defineProperty(exports, "clearICUCache", {
+  enumerable: true,
+  get: function () { return inlineI18nMultiReact.clearICUCache; }
+});
+Object.defineProperty(exports, "detectLocale", {
+  enumerable: true,
+  get: function () { return inlineI18nMultiReact.detectLocale; }
+});
 Object.defineProperty(exports, "en_de", {
   enumerable: true,
   get: function () { return inlineI18nMultiReact.en_de; }
@@ -108,6 +120,14 @@ Object.defineProperty(exports, "parseRichText", {
   enumerable: true,
   get: function () { return inlineI18nMultiReact.parseRichText; }
 });
+Object.defineProperty(exports, "registerFormatter", {
+  enumerable: true,
+  get: function () { return inlineI18nMultiReact.registerFormatter; }
+});
+Object.defineProperty(exports, "restoreLocale", {
+  enumerable: true,
+  get: function () { return inlineI18nMultiReact.restoreLocale; }
+});
 Object.defineProperty(exports, "setLocale", {
   enumerable: true,
   get: function () { return inlineI18nMultiReact.setLocale; }
@@ -116,6 +136,10 @@ Object.defineProperty(exports, "t", {
   enumerable: true,
   get: function () { return inlineI18nMultiReact.t; }
 });
+Object.defineProperty(exports, "useDetectedLocale", {
+  enumerable: true,
+  get: function () { return inlineI18nMultiReact.useDetectedLocale; }
+});
 Object.defineProperty(exports, "useLoadDictionaries", {
   enumerable: true,
   get: function () { return inlineI18nMultiReact.useLoadDictionaries; }

package/dist/client.mjs

@@ -1,3 +1,3 @@
-export { LocaleProvider, RichText, T, clearDictionaries, en_de, en_es, en_fr, en_ja, en_zh, getDictionary, getLoadedLocales, getLocale, hasTranslation, isLoaded, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadAsync, loadDictionaries, loadDictionary, parseRichText, setLocale, t, useLoadDictionaries, useLocale, useRichText, useT, zh_es } from 'inline-i18n-multi-react';
+export { LocaleProvider, RichText, T, clearDictionaries, clearFormatters, clearICUCache, detectLocale, en_de, en_es, en_fr, en_ja, en_zh, getDictionary, getLoadedLocales, getLocale, hasTranslation, isLoaded, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadAsync, loadDictionaries, loadDictionary, parseRichText, registerFormatter, restoreLocale, setLocale, t, useDetectedLocale, useLoadDictionaries, useLocale, useRichText, useT, zh_es } from 'inline-i18n-multi-react';
 //# sourceMappingURL=client.mjs.map
 //# sourceMappingURL=client.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inline-i18n-multi-next",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Next.js integration for inline-i18n-multi",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -51,8 +51,8 @@
     "react": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "inline-i18n-multi": "0.5.0",
-    "inline-i18n-multi-react": "0.5.0"
+    "inline-i18n-multi": "0.7.0",
+    "inline-i18n-multi-react": "0.7.0"
   },
   "devDependencies": {
     "@types/react": "^19.0.2",