@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

License

MIT — HUA Labs

@hua-labs/i18n-core

Package Exports

Readme

@hua-labs/i18n-core

Features

Installation

Quick Start

API

Documentation

Related Packages

License