@hua-labs/i18n-core

Lightweight, production-ready i18n library for React. Delivers zero-flicker language transitions through intelligent caching, SSR-first hydration handling, and built-in state management integration. ~6.5KB gzipped with zero dependencies (React only).

Features

• Zero-flicker — Shows previous language during transition
• SSR-first — Built-in hydration handling, no mismatch issues
• Namespace lazy loading — Load translations on demand
• Pluralization — ICU-compliant plural support via Intl.PluralRules (zero bundle cost)
• Type-safe arrays — tArray() returns string[] without casting
• State management — First-class Zustand support via i18n-core-zustand
• Automatic retry — Exponential backoff for API loader failures
• React Native — Works in Expo and bare RN projects via CJS/ESM dual format
• ~6.5KB gzipped — Zero external dependencies
• Cross-platform — I18nPlatformAdapter for Web, React Native, Flutter bridge
• Generic getRawValue() — type-safe raw value access without casting

Installation

pnpm add @hua-labs/i18n-core

Peer dependencies: react >=19.0.0

Quick Start

import { createCoreI18n, useTranslation } from '@hua-labs/i18n-core';

const I18nProvider = createCoreI18n({
  defaultLanguage: 'ko',
  fallbackLanguage: 'en',
  namespaces: ['common', 'pages'],
});

export default function Layout({ children }) {
  return <I18nProvider>{children}</I18nProvider>;
}

function Welcome() {
  const { t, tPlural } = useTranslation();
  return (
    <div>
      <h1>{t('common:welcome')}</h1>
      <p>{tPlural('common:total_count', 5)}</p>
    </div>
  );
}

API

| Export | Type | Description | |--------|------|-------------| | useTranslation | hook | Main translation hook — returns t, tPlural, tArray, getRawValue and state | | useLanguageChange | hook | Language change hook with validation against supported languages | | useI18n | hook | Full context hook — all translation functions plus language management | | I18nProvider | component | Direct Provider component (for advanced use) | | Translator | class | Core translator class (for manual instantiation) | | ssrTranslate | function | Server-side translation function (no React needed) | | serverTranslate | function | Server-side translate with full config | | webPlatformAdapter | function | Default web adapter — navigator.language detection + window event language sync | | headlessPlatformAdapter | function | No-op adapter for SSR, testing, and Flutter bridge scenarios | | I18nConfig | type | | | I18nContextType | type | | | TranslationParams | type | | | TypedTranslationKeys | type | | | ResolveStringKey | type | | | ResolveArrayKey | type | | | ResolvePluralKey | type | | | PluralValue | type | | | PluralCategory | type | | | I18nPlatformAdapter | interface | Platform adapter interface — implement for React Native or custom environments | | createCoreI18n | function | Create an i18n Provider component with configuration | | CoreProvider | function | Minimal Provider with zero config | | createLanguageProvider | function | Create a Provider with just a language setting | | createNamespaceProvider | function | Create a Provider with just namespace settings | | createCustomLoaderProvider | function | Create a Provider with custom translation loader |

Documentation

Full Documentation

Related Packages

• @hua-labs/i18n-core-zustand
• @hua-labs/eslint-plugin-i18n
• @hua-labs/i18n-loaders
• @hua-labs/i18n-formatters

License

MIT — HUA Labs