@nice2dev/i18n 1.0.3 → 1.0.4

package/README.md

@@ -0,0 +1,199 @@
+# @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
+
+```bash
+npm install @nice2dev/i18n
+```
+
+## Quick Start
+
+### Option 1: Built-in Dictionaries (Simplest)
+
+```tsx
+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:
+
+```tsx
+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.
+
+```tsx
+<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:
+
+```tsx
+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:
+
+```tsx
+import { createTranslator } from '@nice2dev/i18n';
+
+const t = createTranslator('de');
+console.log(t('save', 'Save')); // "Speichern"
+```
+
+### ICU MessageFormat
+
+```tsx
+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
+
+```tsx
+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
+
+```tsx
+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:
+
+```tsx
+<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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice2dev/i18n",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Shared internationalization infrastructure for Nice2Dev UI libraries",
   "type": "module",
   "main": "dist/index.cjs",
@@ -53,5 +53,5 @@
     "translation"
   ],
   "author": "Nice2Dev",
-  "license": "MIT"
+  "license": "SEE LICENSE IN LICENSE"
 }