next-i18n-lite 1.0.3 → 2.0.1

package/README.md

@@ -4,6 +4,7 @@ next-i18n-lite
 
 ## Features
 
+- ✅ auto-configure the i18n library using scaffold
 - ✅ TypeScript support with full type safety
 - ✅ React Context API integration
 - ✅ Automatic RTL support for Arabic.
@@ -25,31 +26,74 @@ yarn add next-i18n-lite
 pnpm add next-i18n-lite
 ```
 
+## Scaffold Prompt
+
+When you install the library, you will see a prompt like this in your terminal:
+⚡ **Prompt:** Do you want to auto-configure the i18n library using scaffold? (Y/n)
+
+✅ Press Enter (default) → scaffold runs  
+❌ Type 'n' → skip
+
+##### Note: it won't effect on the existed files!
 ## Quick Start
 
-File Structure
-create those files inside app
-1- I18nBoundary.tsx (inside lib/)
-2- LocaleSwitcher.tsx (inside components)
-3- lang files inside lib/locales/en.ts and ar.ts
-that's all :D 
+## 📁 Folder Structure
+
+Create the following files **inside the `app/` directory** (recommended):
+
+### Required Files
+
+1. **Language files**
+   - Location: `app/lib/locales/`
+   - Files:
+     - `en.ts` – English translations
+     - `es.ts` – Spanish translations
+     - `fr.ts` – French translations
+     - `pt.ts` – Portuguese translations
+     - `de.ts` – German translations
+     - `ar.ts` – Arabic translations
+
+2. **I18nBoundary.tsx**  
+   - Location: `app/lib/`
+   - Purpose: Client-only i18n wrapper
+
+3. **LocaleSwitcher.tsx**  
+   - Location: `app/components/i18n/`
+   - Purpose: Language switch button
+
+
+
+##### ✅that's all
+---
+
+## 🗂 Directory Tree
+
+```txt
 app/
-├─ layout.tsx                 # Root layout
-├─ globals.css                # Global styles
-├─ Header.tsx                 # Header component (contains nav + LocaleSwitcher)
+├─ layout.tsx              # Root layout
+├─ globals.css             # Global styles
+├─ Header.tsx              # Header (nav + LocaleSwitcher)
+│
 ├─ components/
 │  └─ i18n/
-│     └─ LocaleSwitcher.tsx   # Language switch button
+│     └─ LocaleSwitcher.tsx   # Language switcher button
+│
 └─ lib/
    ├─ I18nBoundary.tsx        # Client-only i18n wrapper
    └─ locales/
-      ├─ en.ts                # English translations
-      └─ ar.ts                # Arabic translations
+      ├─ en.ts               # English translations
+      ├─ es.ts               # Spanish translations
+      ├─ fr.ts               # French translations
+      ├─ pt.ts               # Portuguese translations
+      ├─ de.ts               # German translations
+      └─ ar.ts               # Arabic translations
+```
 ### 1. Create translation files
 
-```typescript
+```bash
 // lib/locales/en.ts
 export const en = {
+  home:'Home',
   common: {
     welcome: 'Welcome',
     loading: 'Loading...',
@@ -59,7 +103,62 @@ export const en = {
     price: 'Price: ${amount}',
   },
 };
+```
+```bash
+// lib/locales/es.ts
+export const es = {
+  home:'Home',
+  common: {
+    welcome: "Bienvenido",
+    loading: "Cargando...",
+  },
+  product: {
+    addToCart: "Agregar al carrito",
+    price: "Precio: ${amount}",
+  },
+};
+```
+```bash
+// lib/locales/fr.ts
+export const fr = {
+  common: {
+    welcome: "Bienvenue",
+    loading: "Chargement...",
+  },
+  product: {
+    addToCart: "Ajouter au panier",
+    price: "Prix : ${amount}",
+  },
+};
+```
+```bash
+// lib/locales/pt.ts
+export const pt = {
+  common: {
+    welcome: "Bem-vindo",
+    loading: "Carregando...",
+  },
+  product: {
+    addToCart: "Adicionar ao carrinho",
+    price: "Preço: ${amount}",
+  },
+};
+```
+```bash
+// lib/locales/de.ts
+export const de = {
+  common: {
+    welcome: "Willkommen",
+    loading: "Wird geladen...",
+  },
+  product: {
+    addToCart: "In den Warenkorb",
+    price: "Preis: ${amount}",
+  },
+};
+```
 
+```bash
 // lib/locales/ar.ts
 export const ar = {
   common: {
@@ -72,39 +171,49 @@ export const ar = {
   },
 };
 ```
-- ✅ feel free to deal with object:
-```typescript
-export const en = {
-    welcome: 'Welcome',
-    loading: 'Loading...',
-}
-```
+
 ### 2. Setup Provider (Next.js App Router)
 
 #### I18nBoundary.tsx
-```typescript
-// lib/I18nBoundary.tsx
+```bash
+// app/lib/I18nBoundary.tsx
 'use client';
-
 import { ReactNode, useEffect, useState } from 'react';
 import { I18nProvider } from 'next-i18n-lite/react';
-
 import { en } from './locales/en';
+import { es } from './locales/es';
+import { fr } from './locales/fr';
+import { pt } from './locales/pt';
+import { de } from './locales/de';
 import { ar } from './locales/ar';
 
-const translations = { en, ar };
+const translations = { en, ar, es, fr, pt, de };
+
+// Supporting Arabic
+const RTL_LOCALES = new Set(['ar']);
+
+function getDirection(locale: string) {
+  return RTL_LOCALES.has(locale) ? 'rtl' : 'ltr';
+}
 
 export function I18nBoundary({ children }: { children: ReactNode }) {
-  const [locale, setLocale] = useState<'en' | 'ar' | null>(null);
+  const [locale, setLocale] = useState<string | null>(null);
 
   useEffect(() => {
-    const saved = localStorage.getItem('locale');
-    setLocale(saved === 'ar' ? 'ar' : 'en');
+    const saved = localStorage.getItem('locale') || 'en';
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setLocale(saved);
+
+    // handle document direction here (ONCE)
+    document.documentElement.lang = saved;
+    document.documentElement.dir = getDirection(saved);
   }, []);
 
+  // hydration-safe gate
   if (!locale) {
     return null;
   }
+
   return (
     <I18nProvider translations={translations} defaultLocale={locale}>
       {children}
@@ -118,11 +227,11 @@ still may face issue for setLocale
 
 Fix: not actually fixed yet but if you don't like red flags in code just 
 
-```typescript
+```bash
 // eslint-disable-next-line react-hooks/set-state-in-effect
 ```
 yup! ignore it :D
-```typescript
+```bash
 // app/layout.tsx
 import { I18nBoundary } from "./lib/I18nBoundary";
 
@@ -139,65 +248,62 @@ export default function RootLayout({ children }) {
 }
 ```
 ### 3. Create LocaleSwitcher.tsx
-/components/ui/LocaleSwitcher.tsx (recommended)
+/components/i18n/LocaleSwitcher.tsx (recommended)
 also i provided 2 options:
 - Choice 1: Single-click toggle button
 - Choice 2:Hover dropdown list
 
 you can ignore styling & lucide-react library both only for example ^^
-```typescript
+```bash
+// components/i18n/LocaleSwitcher.tsx
 'use client';
+
 import { Globe } from "lucide-react";
 import { useI18n } from "next-i18n-lite/react";
-import { useEffect, useState } from "react";
+import { useEffect } from "react";
 
 const languages = [
   { code: 'en', name: 'English' },
+  { code: 'es', name: 'Español' },
+  { code: 'fr', name: 'Français' },
+  { code: 'pt', name: 'Português' },
+  { code: 'de', name: 'Deutsch' },
   { code: 'ar', name: 'العربية' },
 ];
 
 export function LocaleSwitcher() {
   const { locale, setLocale, isRTL } = useI18n();
-  const [mounted, setMounted] = useState(false);
-
-  useEffect(() => {
-     // eslint-disable-next-line react-hooks/set-state-in-effect
-    setMounted(true);
-  }, []);
 
-  if (!mounted) return null;
+  const dropdownPosition = isRTL ? 'left-0' : 'right-0';
 
-  // Toggle between languages on single click
-  const toggleLocale = () => {
-    const persist = locale === 'en' ? 'ar' : 'en';
-    setLocale(persist);
-    localStorage.setItem('locale', persist); // persist choice
+  const changeLocale = (code: string) => {
+    setLocale(code);
+    localStorage.setItem('locale', code);
   };
 
-  // Positioning
-  const dropdownPosition = isRTL ? 'left-0' : 'right-0';
+  // sync document direction (just to make sure eveything in running well in rtl direction)
+  useEffect(() => {
+    document.documentElement.lang = locale;
+    document.documentElement.dir = locale === 'ar' ? 'rtl' : 'ltr';
+  }, [locale]);
 
   return (
     <div className="relative group inline-block">
-      {/* Choice 1: Single-click toggle button */}
-        <Globe color="white" onClick={toggleLocale} className="top-5 "/>
+      <Globe color="white" />
 
-      {/* Choice 2:Hover dropdown list */}
       <div
-        className={`absolute ${dropdownPosition} mt-2 bg-card border border-border rounded-xl shadow-lg opacity-0 invisible group-hover:opacity-100 group-hover:visible transition-all z-50`}
+        className={`absolute ${dropdownPosition} mt-2 bg-card border border-border rounded-xl shadow-lg
+        opacity-0 invisible group-hover:opacity-100 group-hover:visible transition-all z-50`}
       >
         {languages.map((lang) => (
           <button
             key={lang.code}
-            onClick={() => {
-              setLocale(lang.code);
-              localStorage.setItem('locale', lang.code);
-            }}
-            className={`w-full flex items-center gap-3 px-4 py-3 transition-colors first:rounded-t-xl last:rounded-b-xl
+            onClick={() => changeLocale(lang.code)}
+            className={`w-full flex items-center gap-3 px-4 py-3 transition-colors
               ${locale === lang.code ? 'bg-primary/10 text-primary' : 'hover:bg-gray-600'}
             `}
           >
-            <span className="text-sm font-medium">{lang.name}</span>
+            {lang.name}
           </button>
         ))}
       </div>
@@ -205,7 +311,7 @@ export function LocaleSwitcher() {
   );
 }
 ```
-### 4. Use in Components
+### 4. Use in Header Component
 ### `useI18n()`
 const { t, locale, setLocale, isRTL } = useI18n();
 
@@ -214,13 +320,21 @@ Returns:
 - `locale` - Current locale
 - `setLocale(locale)` - Change locale
 - `isRTL` - Boolean indicating RTL direction
-```typescript
+```bash
 'use client';
 import { useI18n } from "next-i18n-lite/react";
 
-export function page() {
+export function Header() {
   const { t } = useI18n();
-
+ const [mounted, setMounted] = useState(false);
+   // To avoid hydration mismatch
+  if (typeof window !== "undefined" && !mounted) {
+    setMounted(true);
+  }
+ 
+  if (!mounted) {
+    return <div className="w-10 h-10" />;
+  }
   return (
     <div>
       <h1>{t('common.welcome')}</h1>
@@ -229,7 +343,41 @@ export function page() {
   );
 }
 ```
-and that's it!!!
+
+
+## Formatters
+
+library also provides helper function to
+ - **handle pluralization**
+according to the current locale.
+---
+
+```bash
+import { pluralize } from "next-i18n-lite"
+export default function Cart() {
+const { t } = useI18n();
+  const items = 1  // 2 try it out
+  return (
+    <p>{pluralize(items, t('unit'), t('units'))}</p>
+  )
+};
+```
+
+### Upcoming Features
+ - **format dates,**  
+ `formatDate(date: Date, locale: string): string`
+ - **format numbers,**
+ `formatNumber(num: number, locale: string): string`
+ - **format currencies,**
+`formatCurrency(amount: number, locale: string, currency = 'USD'): string`
+
+ ```ts
+import { 
+  formatDate,
+  formatNumber,
+  formatCurrency
+} from "next-i18n-lite"
+```
 ## API Reference
 
 ### `useI18n()`
@@ -251,4 +399,4 @@ Returns:
 codex410@gmail.com
 ## License
 
-MIT © IslamAbozeed
+MIT © Islam Abozeed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-i18n-lite",
-  "version": "1.0.3",
+  "version": "2.0.1",
   "description": "Lightweight i18n library for Next.js with TypeScript support",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -19,15 +19,20 @@
   },
   "files": [
     "dist",
+    "scripts",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "postinstall": "node ./scripts/postinstall.mjs || true",
     "prepublishOnly": "npm run build",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
+  "bin":{
+    "setup-i18n": "./scripts/scaffoldI18n.mjs"
+  },
   "keywords": [
     "i18n",
     "internationalization",
@@ -37,7 +42,7 @@
     "localization",
     "translation"
   ],
-  "author": "codexpro410 <codexpro410@gmail.com>",
+  "author": "codexpro410 <codex410@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",

package/scripts/postinstall.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import readline from 'readline';
+import { scaffoldI18n } from './scaffoldI18n.mjs';
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+// Default answer is Yes (y) → user must type 'N' to skip
+rl.question(
+  'Do you want to auto-configure the i18n library using scaffold? (Y/n) ',
+  (answer) => {
+    const normalized = answer.trim().toLowerCase();
+    if (normalized === 'n') {
+      console.log('Skipped scaffold.');
+    } else {
+      console.log('Running scaffold...');
+      scaffoldI18n();
+      console.log('✅ Scaffold completed!');
+    }
+    rl.close();
+  }
+);

package/scripts/scaffoldI18n.mjs

@@ -0,0 +1,169 @@
+import fs from 'fs';
+import path from 'path';
+
+export function scaffoldI18n() {
+// ----------------------
+// 1️⃣ Locales Scaffold
+// ----------------------
+const locales = {
+  en: {
+    home: 'Home',
+    common: { welcome: 'Welcome', loading: 'Loading...' },
+    product: { addToCart: 'Add to Cart', price: 'Price: ${amount}' },
+  },
+  es: {
+    home: 'Inicio',
+    common: { welcome: 'Bienvenido', loading: 'Cargando...' },
+    product: { addToCart: 'Agregar al carrito', price: 'Precio: ${amount}' },
+  },
+  fr: {
+    home: 'Accueil',
+    common: { welcome: 'Bienvenue', loading: 'Chargement...' },
+    product: { addToCart: 'Ajouter au panier', price: 'Prix: ${amount}' },
+  },
+  pt: {
+    home: 'Início',
+    common: { welcome: 'Bem-vindo', loading: 'Carregando...' },
+    product: { addToCart: 'Adicionar ao carrinho', price: 'Preço: ${amount}' },
+  },
+  de: {
+    home: 'Startseite',
+    common: { welcome: 'Willkommen', loading: 'Wird geladen...' },
+    product: { addToCart: 'In den Warenkorb', price: 'Preis: ${amount}' },
+  },
+  ar: {
+    home: 'الصفحة الرئيسية',
+    common: { welcome: 'مرحباً', loading: 'جاري التحميل...' },
+    product: { addToCart: 'أضف إلى السلة', price: 'السعر: ${amount}' },
+  },
+};
+
+const localesDir = path.resolve('./app/lib/locales');
+if (!fs.existsSync(localesDir)) fs.mkdirSync(localesDir, { recursive: true });
+
+for (const [code, content] of Object.entries(locales)) {
+  const filePath = path.join(localesDir, `${code}.ts`);
+  if (!fs.existsSync(filePath)) {
+    const fileContent = `export const ${code} = ${JSON.stringify(content, null, 2)};\n`;
+    fs.writeFileSync(filePath, fileContent, 'utf-8');
+    console.log(`Created locale: ${filePath}`);
+  } else {
+    console.log(`Locale exists: ${filePath}`);
+  }
+}
+
+// ----------------------
+// 2️⃣ I18nBoundary Scaffold
+// ----------------------
+const i18nBoundaryPath = path.resolve('./app/lib/I18nBoundary.tsx');
+if (!fs.existsSync(i18nBoundaryPath)) {
+  const i18nBoundaryContent = `
+// app/lib/I18nBoundary.tsx
+'use client';
+import { ReactNode, useEffect, useState } from 'react';
+import { I18nProvider } from 'next-i18n-lite/react';
+import { en } from './locales/en';
+import { es } from './locales/es';
+import { fr } from './locales/fr';
+import { pt } from './locales/pt';
+import { de } from './locales/de';
+import { ar } from './locales/ar';
+
+const translations = { en, ar, es, fr, pt, de };
+const RTL_LOCALES = new Set(['ar']);
+
+function getDirection(locale: string) {
+  return RTL_LOCALES.has(locale) ? 'rtl' : 'ltr';
+}
+
+export function I18nBoundary({ children }: { children: ReactNode }) {
+  const [locale, setLocale] = useState<string | null>(null);
+
+  useEffect(() => {
+    const saved = localStorage.getItem('locale') || 'en';
+     // eslint-disable-next-line react-hooks/set-state-in-effect
+    setLocale(saved);
+    document.documentElement.lang = saved;
+    document.documentElement.dir = getDirection(saved);
+  }, []);
+
+  if (!locale) return null;
+
+  return (
+    <I18nProvider translations={translations} defaultLocale={locale}>
+      {children}
+    </I18nProvider>
+  );
+}
+`.trim();
+  fs.writeFileSync(i18nBoundaryPath, i18nBoundaryContent, 'utf-8');
+  console.log(`Created: ${i18nBoundaryPath}`);
+} else {
+  console.log(`Exists: ${i18nBoundaryPath}`);
+}
+
+// ----------------------
+// 3️⃣ LocaleSwitcher Scaffold
+// ----------------------
+const localeSwitcherPath = path.resolve('./app/components/i18n/LocaleSwitcher.tsx');
+const localeSwitcherDir = path.dirname(localeSwitcherPath);
+if (!fs.existsSync(localeSwitcherDir)) fs.mkdirSync(localeSwitcherDir, { recursive: true });
+
+if (!fs.existsSync(localeSwitcherPath)) {
+  const localeSwitcherContent = `
+// components/i18n/LocaleSwitcher.tsx
+'use client';
+import { Globe } from "lucide-react";
+import { useI18n } from "next-i18n-lite/react";
+import { useEffect } from "react";
+
+const languages = [
+  { code: 'en', name: 'English' },
+  { code: 'es', name: 'Español' },
+  { code: 'fr', name: 'Français' },
+  { code: 'pt', name: 'Português' },
+  { code: 'de', name: 'Deutsch' },
+  { code: 'ar', name: 'العربية' },
+];
+
+export function LocaleSwitcher() {
+  const { locale, setLocale, isRTL } = useI18n();
+  const dropdownPosition = isRTL ? 'left-0' : 'right-0';
+
+  const changeLocale = (code: string) => {
+    setLocale(code);
+    localStorage.setItem('locale', code);
+  };
+
+    // sync document direction
+  useEffect(() => {
+    document.documentElement.lang = locale;
+    document.documentElement.dir = locale === 'ar' ? 'rtl' : 'ltr';
+  }, [locale]);
+
+  return (
+    <div className="relative group inline-block">
+      <Globe color="white" />
+      <div className={\`absolute \${dropdownPosition} mt-2 bg-card border border-border rounded-xl shadow-lg
+        opacity-0 invisible group-hover:opacity-100 group-hover:visible transition-all z-50\`}>
+        {languages.map((lang) => (
+          <button
+            key={lang.code}
+            onClick={() => changeLocale(lang.code)}
+            className={\`w-full flex items-center gap-3 px-4 py-3 transition-colors
+              \${locale === lang.code ? 'bg-primary/10 text-primary' : 'hover:bg-gray-600'}\`}
+          >
+            {lang.name}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+`.trim();
+  fs.writeFileSync(localeSwitcherPath, localeSwitcherContent, 'utf-8');
+  console.log(`Created: ${localeSwitcherPath}`);
+} else {
+  console.log(`Exists: ${localeSwitcherPath}`);
+}
+}