@nice2dev/i18n

Shared internationalization infrastructure for Nice2Dev UI libraries.

Features

• NiceI18nProvider — React context for translations
• 20 built-in languages — en, pl, de, fr, es, it, pt, nl, sv, no, da, fi, cs, sk, hu, ro, bg, uk, ja, ko, zh, ar
• ICU MessageFormat — pluralization, gender, ordinals, select
• RTL support — Arabic, Hebrew with automatic dir attribute
• Browser detection — detectBrowserLanguage() auto-detects user preference
• Custom translations — plug in your own t() function (react-i18next compatible)

Installation

npm install @nice2dev/i18n

Quick Start

Option 1: Built-in Dictionaries (Simplest)

import { NiceI18nProvider } from '@nice2dev/i18n';
// or re-exported from @nice2dev/ui

function App() {
  const [lang, setLang] = useState('en');

  return (
    <NiceI18nProvider lang={lang}>
      <LanguageSelector value={lang} onChange={setLang} />
      <MyApp />
    </NiceI18nProvider>
  );
}

All Nice2Dev components automatically pick up translations from the provider.

Option 2: Custom Translation Function

If you use react-i18next, i18next, or any other i18n library:

import { useTranslation } from 'react-i18next';
import { NiceI18nProvider } from '@nice2dev/i18n';

function App() {
  const { t } = useTranslation();

  return (
    <NiceI18nProvider t={t}>
      <MyApp />
    </NiceI18nProvider>
  );
}

Option 3: No Provider (English Defaults)

All components work without a provider — they show English by default.

<NiceButton>Click me</NiceButton> {/* Works fine */}

API Reference

NiceI18nProvider

| Prop | Type | Description | | ----------- | -------------------------- | -------------------------------------------------------- | | lang | NiceSupportedLang | Built-in language code (default: 'en') | | t | (key, default) => string | Custom translation function (takes priority over lang) | | overrides | Record<string, string> | Extra translations merged on top of built-in dictionary | | children | ReactNode | App content |

useNiceTranslation

Hook for translating text in components:

import { useNiceTranslation } from '@nice2dev/i18n';

function MyComponent() {
  const { t } = useNiceTranslation();
  return <span>{t('save', 'Save')}</span>; // Returns localized "Save"
}

createTranslator

Create a translator function without React context:

import { createTranslator } from '@nice2dev/i18n';

const t = createTranslator('de');
console.log(t('save', 'Save')); // "Speichern"

ICU MessageFormat

import { formatICU, plural, ordinal, select } from '@nice2dev/i18n';

// Pluralization
formatICU('{count, plural, one{# item} other{# items}}', { count: 5 });
// → "5 items"

// Ordinals
formatICU('{n, selectordinal, one{#st} two{#nd} few{#rd} other{#th}}', { n: 3 });
// → "3rd"

// Gender select
formatICU('{gender, select, male{He} female{She} other{They}} liked it', { gender: 'female' });
// → "She liked it"

RTL Support

import { RTLProvider, useIsRTL, isRTLLanguage } from '@nice2dev/i18n';

// Wrap your app with RTL-aware container
<RTLProvider lang="ar">
  <App /> {/* dir="rtl" automatically applied */}
</RTLProvider>;

// Check if current language is RTL
function MyComponent() {
  const isRTL = useIsRTL();
  return <div style={{ textAlign: isRTL ? 'right' : 'left' }}>...</div>;
}

detectBrowserLanguage

import { detectBrowserLanguage } from '@nice2dev/i18n';

const userLang = detectBrowserLanguage(); // e.g. 'pl' if browser is Polish

Supported Languages

| Code | Language | Native Name | | ---- | ------------ | ----------- | | en | English | English | | pl | Polish | Polski | | de | German | Deutsch | | fr | French | Français | | es | Spanish | Español | | it | Italian | Italiano | | pt | Portuguese | Português | | nl | Dutch | Nederlands | | sv | Swedish | Svenska | | no | Norwegian | Norsk | | da | Danish | Dansk | | fi | Finnish | Suomi | | cs | Czech | Čeština | | sk | Slovak | Slovenčina | | hu | Hungarian | Magyar | | ro | Romanian | Română | | bg | Bulgarian | Български | | uk | Ukrainian | Українська | | ja | Japanese | 日本語 | | ko | Korean | 한국어 | | zh | Chinese | 中文 | | ar | Arabic (RTL) | العربية |

Adding Custom Translations

Extend built-in dictionaries with the overrides prop:

<NiceI18nProvider lang="en" overrides={{ 'myapp.greeting': 'Hello!' }}>
  ...
</NiceI18nProvider>

Or provide your own complete dictionary via t prop.

Translation Keys

All Nice2Dev components use namespaced keys like:

• ok, cancel, save, close — common actions
• nav.home, nav.menu — navigation
• dataGrid.sort, dataGrid.filter — grid-specific
• form.required, form.invalid — validation messages

See src/i18nDictionaries.ts for the full list.

License

MIT