Important: For complete documentation, examples, and best practices, please read the full documentation on GitHub.

inline-i18n-multi-react

React bindings for inline-i18n-multi. Write translations inline in your components.

Installation

npm install inline-i18n-multi-react

Quick Start

import { LocaleProvider, it, T, useT } from 'inline-i18n-multi-react'

function App() {
  return (
    <LocaleProvider locale="ko">
      <MyComponent />
    </LocaleProvider>
  )
}

function MyComponent() {
  return (
    <div>
      {/* Inline function */}
      <p>{it('안녕하세요', 'Hello')}</p>

      {/* T component */}
      <T ko="환영합니다" en="Welcome" ja="ようこそ" />

      {/* With variables */}
      <T ko="{count}개" en="{count} items" count={5} />
    </div>
  )
}

Key-Based Translation with useT

import { useT, loadDictionaries } from 'inline-i18n-multi-react'

loadDictionaries({
  en: { nav: { home: 'Home', about: 'About' } },
  ko: { nav: { home: '홈', about: '소개' } },
})

function Nav() {
  const t = useT()
  return (
    <nav>
      <a href="/">{t('nav.home')}</a>
      <a href="/about">{t('nav.about')}</a>
    </nav>
  )
}

Rich Text

Embed React components within translated strings using <tag> syntax.

import { RichText, useRichText } from 'inline-i18n-multi-react'

// Component approach
function Terms() {
  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>,
      }}
    />
  )
}

// Hook approach
function Legal() {
  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 with useLoadDictionaries

import { useLoadDictionaries, useT } from 'inline-i18n-multi-react'

function Dashboard() {
  const { isLoading, error } = useLoadDictionaries('ko', 'dashboard')
  const t = useT()

  if (isLoading) return <Spinner />
  if (error) return <p>Failed to load translations</p>

  return <h1>{t('dashboard.title')}</h1>
}

Plural Shorthand (v0.7.0)

Concise plural syntax sugar:

function Items({ count }: { count: number }) {
  return (
    <p>
      {it({
        en: '{count, p, item|items}',
        ko: '{count, p, 개|개}',
      }, { count })}
    </p>
  )
}
// count=1 → "1 item", count=5 → "5 items"

// 3-part with zero:
// {count, p, none|item|items} → count=0: "none", count=1: "1 item", count=5: "5 items"

Locale Persistence (v0.7.0)

Auto-save and restore locale to cookie or localStorage:

import { configure, restoreLocale } from 'inline-i18n-multi-react'

// Save to cookie on setLocale()
configure({
  persistLocale: { storage: 'cookie', key: 'LOCALE', expires: 365 }
})

// Or use localStorage
configure({
  persistLocale: { storage: 'localStorage', key: 'LOCALE' }
})

// Restore saved locale
const saved = restoreLocale()  // returns locale string or undefined

Translation Scope (v0.8.0)

Scope translations to a key prefix with useScopedT. Useful for large apps where each component only needs a subset of the dictionary.

import { useScopedT } from 'inline-i18n-multi-react'

function Dashboard() {
  const t = useScopedT('dashboard')
  return (
    <div>
      <h1>{t('title')}</h1>     {/* resolves to 'dashboard.title' */}
      <p>{t('subtitle')}</p>    {/* resolves to 'dashboard.subtitle' */}
    </div>
  )
}

You can also create a reusable scope with createScope:

import { createScope } from 'inline-i18n-multi-react'

const scope = createScope('settings.profile')

function ProfileForm() {
  const t = useScopedT(scope)
  return <label>{t('name')}</label>  {/* resolves to 'settings.profile.name' */}
}

Context System (v0.9.0)

Select translations based on context. Pass _context to t() to choose between contextual variants defined in your dictionaries.

import { useT, loadDictionaries } from 'inline-i18n-multi-react'

loadDictionaries({
  en: {
    greeting: 'Hello',
    'greeting#formal': 'Good day',
    'greeting#casual': 'Hey',
  },
  ko: {
    greeting: '안녕하세요',
    'greeting#formal': '안녕하십니까',
    'greeting#casual': '안녕',
  },
})

function Greeting() {
  const t = useT()
  return (
    <div>
      <p>{t('greeting')}</p>                              {/* "Hello" */}
      <p>{t('greeting', { _context: 'formal' })}</p>      {/* "Good day" */}
      <p>{t('greeting', { _context: 'casual' })}</p>      {/* "Hey" */}
    </div>
  )
}

Automatic Locale Detection

import { LocaleProvider, useDetectedLocale } from 'inline-i18n-multi-react'

function App() {
  return (
    <LocaleProvider locale="en">
      <AutoDetect />
    </LocaleProvider>
  )
}

function AutoDetect() {
  useDetectedLocale({
    supportedLocales: ['en', 'ko', 'ja'],
    defaultLocale: 'en',
    sources: ['cookie', 'navigator'],
  })

  return <Content />
}

API

React-Specific

| Export | Description | |---|---| | LocaleProvider | Context provider for locale | | useLocale() | Get/set current locale via context | | useT() | Hook returning key-based t() function | | T | Translation component with language props | | RichText | Rich text translation component | | useRichText(components) | Hook for rich text translations | | useLoadDictionaries(locale, namespace?) | Lazy loading hook with loading/error state | | useScopedT(prefix) | Hook returning scoped t() bound to a key prefix | | useDetectedLocale(options) | Auto-detect and set locale on mount |

Re-exported from Core

Inline translations: it, it_ja, it_zh, it_es, it_fr, it_de, en_ja, en_zh, en_es, en_fr, en_de, ja_zh, ja_es, zh_es

Locale management: getLocale, setLocale

Key-based translations: t, loadDictionaries, loadDictionary, clearDictionaries, hasTranslation, getLoadedLocales, getDictionary, loadAsync, isLoaded, createScope

Configuration: configure, getConfig, resetConfig

Rich text parsing: parseRichText

Custom formatters: registerFormatter, clearFormatters

Locale detection: detectLocale

ICU cache & persistence: clearICUCache, restoreLocale

Documentation

Please read the full documentation on GitHub for complete API reference, advanced patterns, and best practices.

License

MIT