@arc-js/intl 0.0.2

package/README.md

@@ -0,0 +1,575 @@
+# @arc-js/intl
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-007ACC)
+![React](https://img.shields.io/badge/React-19+-61DAFB)
+![Vite](https://img.shields.io/badge/Vite-6+-646CFF)
+
+**@arc-js/intl** est un système de gestion d'internationalisation (i18n) modulaire et performant pour les applications React avec TypeScript/JavaScript. Il fournit une gestion avancée des traductions, un chargement dynamique des modules, et une intégration transparente avec l'écosystème Arc.
+
+## ✨ Fonctionnalités Principales
+
+### 🌍 Gestion Multi-Langue Avancée
+- **Support de plusieurs locales** avec détection automatique
+- **Chargement dynamique** des fichiers de traduction
+- **Gestion des pluriels** basée sur les règles Intl
+- **Interpolation de variables** dans les traductions
+
+### 📦 Architecture Modulaire
+- **Traductions par module** avec isolation complète
+- **Chargement à la demande** des traductions des modules
+- **Fusion intelligente** des traductions hiérarchiques
+- **Support des namespaces** pour une organisation claire
+
+### ⚡ Performance Optimisée
+- **Chargement paresseux** des fichiers de traduction
+- **Mémoire cache** des traductions chargées
+- **Minimal bundle size** grâce au code splitting
+- **Hot reload** pendant le développement
+
+### 🔧 Intégration Facile
+- **Provider React** simple à configurer
+- **Hooks personnalisés** pour une utilisation intuitive
+- **Compatibilité totale** avec TypeScript
+- **Intégration avec @arc-js/cooks** pour la persistance
+
+## 📦 Installation
+
+### Via npm/yarn/pnpm
+
+```bash
+npm install @arc-js/intl @arc-js/cooks react
+# ou
+yarn add @arc-js/intl @arc-js/cooks react
+# ou
+pnpm add @arc-js/intl @arc-js/cooks react
+```
+
+### Dépendances requises
+- React 19+
+- @arc-js/cooks 0.0.3+
+- TypeScript 5.0+ (recommandé)
+- Vite (pour le chargement dynamique)
+
+## 🚀 Démarrage Rapide
+
+### Structure de projet recommandée
+
+```
+src/
+├── locales/
+│   ├── en.json          # Traductions anglaises de base
+│   └── fr.json          # Traductions françaises de base
+├── modules/
+│   ├── admin/
+│   │   └── locales/
+│   │       ├── en.json  # Traductions admin anglaises
+│   │       └── fr.json  # Traductions admin françaises
+│   └── dashboard/
+│       └── locales/
+│           ├── en.json  # Traductions dashboard anglaises
+│           └── fr.json  # Traductions dashboard françaises
+└── main.tsx
+```
+
+### Configuration de base
+
+```typescript
+// main.tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { ArcIntlProvider } from '@arc-js/intl';
+
+const App = () => {
+  return (
+    <div>
+      <h1>Mon Application Internationalisée</h1>
+      {/* Votre contenu ici */}
+    </div>
+  );
+};
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <ArcIntlProvider supportedLocales={['en', 'fr', 'es']}>
+      <App />
+    </ArcIntlProvider>
+  </React.StrictMode>
+);
+```
+
+### Fichiers de traduction
+
+```json
+// locales/en.json
+{
+  "common": {
+    "welcome": "Welcome to our application",
+    "login": "Sign in",
+    "logout": "Sign out",
+    "save": "Save changes"
+  },
+  "errors": {
+    "required": "This field is required",
+    "email": "Please enter a valid email address"
+  }
+}
+
+// modules/admin/locales/en.json
+{
+  "admin": {
+    "dashboard": {
+      "title": "Admin Dashboard",
+      "users": "Manage Users",
+      "settings": "System Settings"
+    }
+  }
+}
+```
+
+## 📚 Documentation API
+
+### Hook useTranslation
+
+```typescript
+import { useTranslation } from '@arc-js/intl';
+
+const MyComponent = () => {
+  const {
+    t,                    // Fonction de traduction principale
+    changeLocale,         // Changer la locale
+    currentLocale,        // Locale actuelle
+    isLoading            // État de chargement
+  } = useTranslation('admin'); // Optionnel: nom du module
+
+  // Exemple d'utilisation
+  const handleChangeLanguage = () => {
+    changeLocale(currentLocale === 'en' ? 'fr' : 'en');
+  };
+
+  return (
+    <div>
+      <h1>{t('admin.dashboard.title')}</h1>
+      <p>{t('common.welcome')}</p>
+      <button onClick={handleChangeLanguage}>
+        {t('common.change_language')}
+      </button>
+    </div>
+  );
+};
+```
+
+### ArcIntlProvider
+
+```typescript
+import { ArcIntlProvider } from '@arc-js/intl';
+
+// Configuration avec locales personnalisées
+<ArcIntlProvider 
+  supportedLocales={['en', 'fr', 'es', 'de']}
+>
+  {children}
+</ArcIntlProvider>
+
+// Configuration par défaut (en, fr)
+<ArcIntlProvider>
+  {children}
+</ArcIntlProvider>
+```
+
+## 🔧 Utilisation Avancée
+
+### Traductions avec paramètres
+
+```typescript
+// locales/en.json
+{
+  "greeting": "Hello, {name}!",
+  "items_count": "You have {count} item{count, plural, one {} other {s}}"
+}
+
+// Utilisation dans le composant
+const Greeting = ({ userName, itemCount }) => {
+  const { t } = useTranslation();
+  
+  return (
+    <div>
+      <p>{t('greeting', { name: userName })}</p>
+      <p>{t('items_count', { count: itemCount })}</p>
+    </div>
+  );
+};
+```
+
+### Pluriels et contextes
+
+```typescript
+// locales/en.json
+{
+  "messages": {
+    "unread": {
+      "one": "You have one unread message",
+      "other": "You have {count} unread messages"
+    }
+  },
+  "action": {
+    "save": "Save",
+    "save_context": {
+      "draft": "Save as draft",
+      "final": "Save and publish"
+    }
+  }
+}
+
+// Utilisation
+const Notification = ({ unreadCount }) => {
+  const { t } = useTranslation();
+  
+  return (
+    <div>
+      {/* Pluriel automatique */}
+      <p>{t('messages.unread', { count: unreadCount })}</p>
+      
+      {/* Contexte spécifique */}
+      <button>{t('action.save', {}, { context: 'draft' })}</button>
+      <button>{t('action.save', {}, { context: 'final' })}</button>
+    </div>
+  );
+};
+```
+
+### Chargement dynamique de modules
+
+```typescript
+import { useEffect } from 'react';
+import { useArcIntl } from '@arc-js/intl';
+
+const AdminModule = () => {
+  const { loadModuleTranslations, t } = useArcIntl();
+  
+  useEffect(() => {
+    // Charger les traductions du module admin à la demande
+    loadModuleTranslations('admin');
+  }, []);
+  
+  return (
+    <div>
+      <h1>{t('admin.dashboard.title', {}, { moduleName: 'admin' })}</h1>
+    </div>
+  );
+};
+```
+
+## 🎯 Exemples Complets
+
+### Exemple 1 : Sélecteur de langue
+
+```typescript
+import { useTranslation } from '@arc-js/intl';
+
+const LanguageSwitcher = () => {
+  const { currentLocale, changeLocale, t } = useTranslation();
+  
+  const languages = [
+    { code: 'en', name: 'English' },
+    { code: 'fr', name: 'Français' },
+    { code: 'es', name: 'Español' },
+    { code: 'de', name: 'Deutsch' }
+  ];
+  
+  return (
+    <div className="language-switcher">
+      <span>{t('common.language')}:</span>
+      <select 
+        value={currentLocale}
+        onChange={(e) => changeLocale(e.target.value)}
+      >
+        {languages.map(lang => (
+          <option key={lang.code} value={lang.code}>
+            {lang.name}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+### Exemple 2 : Formulaire internationalisé
+
+```typescript
+import { useTranslation } from '@arc-js/intl';
+import { useState } from 'react';
+
+const ContactForm = () => {
+  const { t } = useTranslation();
+  const [formData, setFormData] = useState({
+    name: '',
+    email: '',
+    message: ''
+  });
+  
+  const handleSubmit = (e) => {
+    e.preventDefault();
+    // Soumettre le formulaire
+  };
+  
+  return (
+    <form onSubmit={handleSubmit} className="contact-form">
+      <div className="form-group">
+        <label>{t('form.name')}</label>
+        <input
+          value={formData.name}
+          onChange={e => setFormData({...formData, name: e.target.value})}
+          placeholder={t('form.name_placeholder')}
+        />
+        {!formData.name && (
+          <span className="error">{t('errors.required')}</span>
+        )}
+      </div>
+      
+      <div className="form-group">
+        <label>{t('form.email')}</label>
+        <input
+          type="email"
+          value={formData.email}
+          onChange={e => setFormData({...formData, email: e.target.value})}
+          placeholder={t('form.email_placeholder')}
+        />
+      </div>
+      
+      <div className="form-group">
+        <label>{t('form.message')}</label>
+        <textarea
+          value={formData.message}
+          onChange={e => setFormData({...formData, message: e.target.value})}
+          placeholder={t('form.message_placeholder')}
+          rows={4}
+        />
+      </div>
+      
+      <button type="submit">
+        {t('form.submit')}
+      </button>
+    </form>
+  );
+};
+```
+
+### Exemple 3 : Dashboard avec modules multiples
+
+```typescript
+import { useArcIntl } from '@arc-js/intl';
+import { useEffect } from 'react';
+
+const Dashboard = () => {
+  const { t, loadModuleTranslations, currentLocale } = useArcIntl();
+  
+  // Charger les traductions de plusieurs modules
+  useEffect(() => {
+    const loadModules = async () => {
+      await loadModuleTranslations('admin');
+      await loadModuleTranslations('analytics');
+      await loadModuleTranslations('reports');
+    };
+    loadModules();
+  }, [currentLocale]);
+  
+  return (
+    <div className="dashboard">
+      <header>
+        <h1>{t('dashboard.title', {}, { moduleName: 'admin' })}</h1>
+        <p>{t('dashboard.welcome_message', { user: 'John Doe' })}</p>
+      </header>
+      
+      <section className="stats">
+        <div className="stat-card">
+          <h3>{t('analytics.visitors', {}, { moduleName: 'analytics' })}</h3>
+          <p>1,234</p>
+        </div>
+        
+        <div className="stat-card">
+          <h3>{t('reports.monthly', {}, { moduleName: 'reports' })}</h3>
+          <p>{t('reports.growth', { percent: '15%' })}</p>
+        </div>
+      </section>
+      
+      <footer>
+        <p>{t('common.last_updated', { date: new Date().toLocaleDateString(currentLocale) })}</p>
+      </footer>
+    </div>
+  );
+};
+```
+
+## 🔧 Configuration Avancée
+
+### Configuration Vite
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@arc-js/intl': '@arc-js/intl/index.js'
+    }
+  }
+});
+```
+
+### Configuration TypeScript
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["DOM", "DOM.Iterable", "ES2020"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "node_modules/@arc-js/intl/**/*"]
+}
+```
+
+### Variables d'environnement
+
+```bash
+# .env
+VITE_DEFAULT_LOCALE=en
+VITE_SUPPORTED_LOCALES=en,fr,es
+VITE_TRANSLATION_DEBUG=true
+```
+
+## 🛡️ Gestion des Erreurs
+
+### Fallback et logs
+
+```typescript
+// En mode développement, les clés manquantes sont loggées
+const MissingKeyHandler = () => {
+  const { t } = useTranslation();
+  
+  // Si la clé n'existe pas, elle est retournée telle quelle
+  const title = t('nonexistent.key'); // Retourne: "nonexistent.key"
+  
+  // Avec une valeur par défaut
+  const subtitle = t('another.missing.key', {}, { 
+    defaultValue: 'Default text' 
+  }); // Retourne: "Default text"
+  
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{subtitle}</p>
+    </div>
+  );
+};
+```
+
+### Validation des traductions
+
+```typescript
+// Script de validation des traductions
+import fs from 'fs';
+import path from 'path';
+
+const validateTranslations = (locale: string) => {
+  const basePath = path.join(__dirname, 'locales', `\${locale}.json`);
+  const baseTranslations = JSON.parse(fs.readFileSync(basePath, 'utf-8'));
+  
+  // Vérifier les clés de base
+  const requiredKeys = ['common', 'errors', 'form'];
+  requiredKeys.forEach(key => {
+    if (!baseTranslations[key]) {
+      console.warn(`Missing required namespace "\${key}" in \${locale}`);
+    }
+  });
+  
+  // Vérifier la structure des pluriels
+  Object.entries(baseTranslations).forEach(([namespace, translations]) => {
+    // Logique de validation spécifique
+  });
+};
+```
+
+## 📋 Table des Conventions
+
+### Structure des fichiers JSON
+
+| Chemin | Description | Exemple |
+|--------|-------------|---------|
+| `locales/{locale}.json` | Traductions de base | `locales/en.json` |
+| `modules/{module}/locales/{locale}.json` | Traductions du module | `modules/admin/locales/fr.json` |
+| `public/locales/{locale}.json` | Traductions statiques (optionnel) | `public/locales/es.json` |
+
+### Clés de traduction
+
+| Format | Description | Exemple |
+|--------|-------------|---------|
+| `namespace.key` | Clé simple | `common.save` |
+| `namespace.nested.key` | Clé imbriquée | `form.contact.email` |
+| `key_{context}` | Avec contexte | `save_draft`, `save_final` |
+| `key_{pluralForm}` | Forme plurielle | `item_one`, `item_other` |
+
+### Paramètres supportés
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `count` | number | Pour la gestion des pluriels |
+| `context` | string | Contexte spécifique (draft, final, etc.) |
+| `moduleName` | string | Module cible pour la traduction |
+| `defaultValue` | string | Valeur par défaut si la clé n'existe pas |
+
+## 🔧 Build et Développement
+
+### Scripts recommandés
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "type-check": "tsc --noEmit",
+    "extract-translations": "node scripts/extract-keys.js",
+    "validate-translations": "node scripts/validate-translations.js"
+  }
+}
+```
+
+### Extraction des clés de traduction
+
+```javascript
+// scripts/extract-keys.js
+import { extractKeysFromFiles } from './translation-utils';
+
+// Extraire toutes les clés utilisées dans les composants
+const keys = extractKeysFromFiles('src/**/*.{tsx,ts}');
+fs.writeFileSync('translation-keys.json', JSON.stringify(keys, null, 2));
+```
+
+## 📄 Licence
+
+MIT License - Voir le fichier [LICENSE](LICENSE) pour plus de détails.
+
+## 🐛 Signaler un Bug
+
+Envoyez-nous un mail à l'adresse `contact.inicode@gmail.com` pour :
+- Signaler un bug
+- Proposer une amélioration
+- Poser une question sur l'utilisation
+- Demander une nouvelle fonctionnalité
+
+---
+
+**@arc-js/intl** - La solution d'internationalisation modulaire pour React et TypeScript.
+
+*Développé par l'équipe INICODE*

package/config.d.ts

@@ -0,0 +1,13 @@
+declare const DEFAULT_LOCALE = "en";
+declare const SUPPORTED_LOCALES: string[];
+declare const COOKIE_NAME = "app_locale";
+type Locale = typeof SUPPORTED_LOCALES[number];
+declare const getSavedLocale: (supportedLocales?: string[]) => string;
+declare const saveLocale: (locale: string) => void;
+declare const PATH_CONFIG: {
+    SRC_DIR: string;
+};
+declare const SRC_DIR: string;
+
+export { COOKIE_NAME, DEFAULT_LOCALE, PATH_CONFIG, SRC_DIR, SUPPORTED_LOCALES, getSavedLocale, saveLocale };
+export type { Locale };