@asafarim/shared-i18n 0.8.0 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +71 -1
  2. package/demo/README.md +148 -0
  3. package/package.json +84 -85
package/README.md CHANGED
@@ -201,7 +201,77 @@ interface LanguageSwitcherProps {
201
201
  />
202
202
  ```
203
203
 
204
- ## API Reference
204
+ ## Country / Language Selector Integration
205
+
206
+ For applications serving multiple countries with different official languages, integrate [@asafarim/country-language-selector](https://www.npmjs.com/package/@asafarim/country-language-selector):
207
+
208
+ ```bash
209
+ pnpm add @asafarim/country-language-selector
210
+ ```
211
+
212
+ ### Example: Belgium, Switzerland, Canada
213
+
214
+ ```tsx
215
+ import { CountryLanguageSelector } from '@asafarim/country-language-selector';
216
+ import { useTranslation } from '@asafarim/shared-i18n';
217
+
218
+ const countries = [
219
+ {
220
+ code: 'BE',
221
+ name: 'Belgium',
222
+ nativeName: 'België',
223
+ flag: '🇧🇪',
224
+ languages: [
225
+ { code: 'nl', label: 'Dutch', nativeLabel: 'Nederlands' },
226
+ { code: 'fr', label: 'French', nativeLabel: 'Français' },
227
+ { code: 'de', label: 'German', nativeLabel: 'Deutsch' }
228
+ ]
229
+ },
230
+ {
231
+ code: 'CH',
232
+ name: 'Switzerland',
233
+ nativeName: 'Schweiz',
234
+ flag: '🇨🇭',
235
+ languages: [
236
+ { code: 'de', label: 'German', nativeLabel: 'Deutsch' },
237
+ { code: 'fr', label: 'French', nativeLabel: 'Français' },
238
+ { code: 'it', label: 'Italian', nativeLabel: 'Italiano' }
239
+ ]
240
+ },
241
+ {
242
+ code: 'CA',
243
+ name: 'Canada',
244
+ nativeName: 'Canada',
245
+ flag: '🇨🇦',
246
+ languages: [
247
+ { code: 'en', label: 'English' },
248
+ { code: 'fr', label: 'French', nativeLabel: 'Français' }
249
+ ]
250
+ }
251
+ ];
252
+
253
+ export function CountryLanguageBar() {
254
+ const { i18n } = useTranslation();
255
+
256
+ return (
257
+ <CountryLanguageSelector
258
+ countries={countries}
259
+ defaultValue={{ country: 'BE', language: 'nl' }}
260
+ persistKey="user-locale"
261
+ triggerVariant="compact"
262
+ onChange={(locale) => i18n.changeLanguage(locale.language)}
263
+ />
264
+ );
265
+ }
266
+ ```
267
+
268
+ ### Integration Notes
269
+
270
+ - The selector automatically handles country→language relationships
271
+ - Language changes integrate seamlessly with shared-i18n's `useTranslation()` hook
272
+ - Locale persists to localStorage for user preference retention
273
+ - See [full documentation](https://alisafari-it.github.io/country-language-switch/#/get-started) for additional props and customization options
274
+
205
275
 
206
276
  ### initI18n(config?: I18nConfig)
207
277
 
package/demo/README.md ADDED
@@ -0,0 +1,148 @@
1
+ # @asafarim/shared-i18n Demo
2
+
3
+ A comprehensive interactive demo application showcasing the features of [@asafarim/shared-i18n](../README.md) and its integration with [@asafarim/country-language-selector](https://www.npmjs.com/package/@asafarim/country-language-selector).
4
+
5
+ ## Live Demo
6
+
7
+ View the demo online at: [https://alisafari-it.github.io/shared-i18n/](https://alisafari-it.github.io/shared-i18n/)
8
+
9
+ ## Local Development
10
+
11
+ ### Prerequisites
12
+
13
+ - Node.js 18+
14
+ - pnpm 10+
15
+
16
+ ### Setup
17
+
18
+ ```bash
19
+ # From the root directory
20
+ pnpm install
21
+
22
+ # Build the shared-i18n package
23
+ pnpm run build
24
+
25
+ # Navigate to demo and start dev server
26
+ cd demo
27
+ pnpm run dev
28
+ ```
29
+
30
+ The demo will be available at `http://localhost:5173/shared-i18n/`
31
+
32
+ ### Build
33
+
34
+ ```bash
35
+ pnpm run build
36
+ ```
37
+
38
+ Output files are generated in `dist/`
39
+
40
+ ## Demo Features
41
+
42
+ ### Tab 1: Overview
43
+
44
+ Highlights the key features and use cases of shared-i18n:
45
+ - Multi-language support with cookie persistence
46
+ - Built-in language detection and fallback
47
+ - TypeScript support with full type safety
48
+ - Seamless integration with react-i18next
49
+
50
+ ### Tab 2: Get Started
51
+
52
+ Step-by-step guide to integrate shared-i18n into your React application:
53
+ 1. Install the package
54
+ 2. Initialize i18n in your app
55
+ 3. Use the `useLanguage` hook
56
+ 4. Translate with `useTranslation`
57
+ 5. Leverage cookie persistence
58
+ 6. Optional backend synchronization
59
+
60
+ Includes code examples and pro tips for each step.
61
+
62
+ ### Tab 3: Demo
63
+
64
+ Live examples of the `LanguageSwitcher` component:
65
+ - **Buttons Variant** — Individual language buttons
66
+ - **Select Dropdown** — Native HTML dropdown
67
+ - **Icon Dropdown** — Compact flag emoji selector
68
+ - **Toggle Button** — For exactly 2 languages
69
+ - **Limited Languages** — Filter languages per component
70
+ - **Translations Panel** — View actual translations from common and identity-portal namespaces
71
+ - **Interpolation & Trans Component** — Dynamic string interpolation examples
72
+
73
+ ### Tab 4: Country Selector
74
+
75
+ Live examples of the `CountryLanguageSelector` component:
76
+ - **Default Selector** — Standard country/language picker with compact mode
77
+ - **Full Trigger Variant** — Display full country and language names
78
+ - **Custom Trigger** — Implement your own button styling and layout
79
+
80
+ ### Header Features
81
+
82
+ - **Country/Language Selector** — In the header, select from Belgium, Switzerland, and Canada
83
+ - **Language Support** — English, Dutch, French, German, Italian (6+ languages total)
84
+ - **Dark/Light Theme Toggle** — Accessible theme switching
85
+ - **Links** — GitHub and NPM package links
86
+
87
+ ## Supported Languages
88
+
89
+ The demo includes translations for:
90
+ - 🇬🇧 English (en)
91
+ - 🇳🇱 Dutch (nl)
92
+ - 🇫🇷 French (fr)
93
+ - 🇩🇪 German (de)
94
+ - 🇮🇹 Italian (it)
95
+
96
+ Language selection persists to localStorage automatically.
97
+
98
+ ## Project Structure
99
+
100
+ ```
101
+ demo/
102
+ ├── src/
103
+ │ ├── components/
104
+ │ │ ├── LanguageSwitcherDemo.tsx # Shared-i18n examples
105
+ │ │ ├── CountryLanguageDemo.tsx # Country selector examples
106
+ │ │ ├── LanguageBar.tsx # Header with country selector
107
+ │ │ ├── OverviewSection.tsx # Overview tab
108
+ │ │ ├── GetStartedSection.tsx # Get started tab
109
+ │ │ ├── Panel.tsx # Reusable panel wrapper
110
+ │ │ ├── KeyTable.tsx # Translations table
111
+ │ │ └── StatusCard.tsx # Language sync status
112
+ │ ├── locales/
113
+ │ │ ├── en/demo.json
114
+ │ │ ├── nl/demo.json
115
+ │ │ ├── fr/demo.json
116
+ │ │ ├── de/demo.json
117
+ │ │ └── it/demo.json
118
+ │ ├── App.tsx # Main app with tabs
119
+ │ ├── main.tsx # Entry point
120
+ │ └── index.css # Global styles
121
+ ├── package.json
122
+ └── vite.config.ts
123
+ ```
124
+
125
+ ## Key Technologies
126
+
127
+ - **React 19** — UI library
128
+ - **TypeScript** — Type safety
129
+ - **Vite** — Build tool and dev server
130
+ - **i18next** — Translation engine
131
+ - **react-i18next** — React bindings for i18next
132
+ - **ASafariM Design Tokens** — Design system styling
133
+
134
+ ## Related Packages
135
+
136
+ - [@asafarim/shared-i18n](../README.md) — Core i18n package
137
+ - [@asafarim/country-language-selector](https://www.npmjs.com/package/@asafarim/country-language-selector) — Country/language selector component
138
+ - [@asafarim/design-tokens](https://www.npmjs.com/package/@asafarim/design-tokens) — Design system
139
+
140
+ ## License
141
+
142
+ MIT
143
+
144
+ ## Support
145
+
146
+ For issues or questions about the shared-i18n package, see the [main README](../README.md).
147
+
148
+ For issues specific to the country-language-selector, see its [documentation](https://alisafari-it.github.io/country-language-switch/).
package/package.json CHANGED
@@ -1,86 +1,85 @@
1
- {
2
- "name": "@asafarim/shared-i18n",
3
- "description": "A shared i18n package for React applications",
4
- "version": "0.8.0",
5
- "type": "module",
6
- "files": [
7
- "dist",
8
- "demo",
9
- "README.md"
10
- ],
11
- "main": "dist/index.js",
12
- "types": "dist/index.d.ts",
13
- "scripts": {
14
- "build": "tsc -b && node ./scripts/copy-css.js",
15
- "demo": "pnpm run build && cd demo && pnpm run dev",
16
- "prepublishOnly": "pnpm run build",
17
- "release": "node ./scripts/release.js"
18
- },
19
- "exports": {
20
- ".": {
21
- "types": "./dist/index.d.ts",
22
- "default": "./dist/index.js"
23
- },
24
- "./config": {
25
- "types": "./dist/config/i18n.d.ts",
26
- "default": "./dist/config/i18n.js"
27
- },
28
- "./hooks": {
29
- "types": "./dist/hooks/useLanguage.d.ts",
30
- "default": "./dist/hooks/useLanguage.js"
31
- },
32
- "./utils": {
33
- "types": "./dist/utils/languageUtils.d.ts",
34
- "default": "./dist/utils/languageUtils.js"
35
- },
36
- "./components": {
37
- "types": "./dist/components/LanguageSwitcher.d.ts",
38
- "default": "./dist/components/LanguageSwitcher.js"
39
- },
40
- "./locales/*": "./locales/*"
41
- },
42
- "peerDependencies": {
43
- "react": "^18.2.0 || ^19.0.0",
44
- "react-dom": "^18.2.0 || ^19.0.0"
45
- },
46
- "dependencies": {
47
- "i18next": "^23.15.1",
48
- "react-i18next": "^13.5.0",
49
- "@asafarim/design-tokens": "^0.5.0",
50
- "i18next-browser-languagedetector": "^7.2.0"
51
- },
52
- "devDependencies": {
53
- "@types/node": "^24.3.1",
54
- "@types/react": "^18.2.0 || ^19.0.0",
55
- "@types/react-dom": "^18.2.0 || ^19.0.0",
56
- "typescript": "~5.8.3"
57
- },
58
- "keywords": [
59
- "asafarim",
60
- "react",
61
- "i18n",
62
- "i18next",
63
- "internationalization",
64
- "language",
65
- "localization",
66
- "react-i18next",
67
- "react-internationalization",
68
- "react-localization",
69
- "react-language",
70
- "react-localization",
71
- "typescript"
72
- ],
73
- "author": "Ali Safari <asafarim@gmail.com>",
74
- "license": "MIT",
75
- "repository": {
76
- "type": "git",
77
- "url": "https://github.com/AliSafari-IT/shared-i18n.git"
78
- },
79
- "bugs": {
80
- "url": "https://github.com/AliSafari-IT/shared-i18n/issues"
81
- },
82
- "homepage": "https://alisafari-it.github.io/shared-i18n",
83
- "publishConfig": {
84
- "access": "public"
85
- }
1
+ {
2
+ "name": "@asafarim/shared-i18n",
3
+ "description": "A shared i18n package for React applications",
4
+ "version": "0.8.1",
5
+ "type": "module",
6
+ "files": [
7
+ "dist",
8
+ "demo",
9
+ "README.md"
10
+ ],
11
+ "main": "dist/index.js",
12
+ "types": "dist/index.d.ts",
13
+ "exports": {
14
+ ".": {
15
+ "types": "./dist/index.d.ts",
16
+ "default": "./dist/index.js"
17
+ },
18
+ "./config": {
19
+ "types": "./dist/config/i18n.d.ts",
20
+ "default": "./dist/config/i18n.js"
21
+ },
22
+ "./hooks": {
23
+ "types": "./dist/hooks/useLanguage.d.ts",
24
+ "default": "./dist/hooks/useLanguage.js"
25
+ },
26
+ "./utils": {
27
+ "types": "./dist/utils/languageUtils.d.ts",
28
+ "default": "./dist/utils/languageUtils.js"
29
+ },
30
+ "./components": {
31
+ "types": "./dist/components/LanguageSwitcher.d.ts",
32
+ "default": "./dist/components/LanguageSwitcher.js"
33
+ },
34
+ "./locales/*": "./locales/*"
35
+ },
36
+ "peerDependencies": {
37
+ "react": "^18.2.0 || ^19.0.0",
38
+ "react-dom": "^18.2.0 || ^19.0.0"
39
+ },
40
+ "dependencies": {
41
+ "i18next": "^23.15.1",
42
+ "react-i18next": "^13.5.0",
43
+ "@asafarim/design-tokens": "^0.5.0",
44
+ "i18next-browser-languagedetector": "^7.2.0"
45
+ },
46
+ "devDependencies": {
47
+ "@types/node": "^24.3.1",
48
+ "@types/react": "^18.2.0 || ^19.0.0",
49
+ "@types/react-dom": "^18.2.0 || ^19.0.0",
50
+ "typescript": "~5.8.3"
51
+ },
52
+ "keywords": [
53
+ "asafarim",
54
+ "react",
55
+ "i18n",
56
+ "i18next",
57
+ "internationalization",
58
+ "language",
59
+ "localization",
60
+ "react-i18next",
61
+ "react-internationalization",
62
+ "react-localization",
63
+ "react-language",
64
+ "react-localization",
65
+ "typescript"
66
+ ],
67
+ "author": "Ali Safari <asafarim@gmail.com>",
68
+ "license": "MIT",
69
+ "repository": {
70
+ "type": "git",
71
+ "url": "https://github.com/AliSafari-IT/shared-i18n.git"
72
+ },
73
+ "bugs": {
74
+ "url": "https://github.com/AliSafari-IT/shared-i18n/issues"
75
+ },
76
+ "homepage": "https://alisafari-it.github.io/shared-i18n",
77
+ "publishConfig": {
78
+ "access": "public"
79
+ },
80
+ "scripts": {
81
+ "build": "tsc -b && node ./scripts/copy-css.js",
82
+ "demo": "pnpm run build && cd demo && pnpm run dev",
83
+ "release": "node ./scripts/release.js"
84
+ }
86
85
  }