Dictionnaires i18n Next.js et fournisseurs (`nextjs-i18n-usage`)

Dictionnaires i18n Next.js et fournisseurs (nextjs-i18n-usage)

Standards d'ingénierie, hooks et modèles de fournisseurs pour consommer les traductions next-intl dans les composants serveur React (RSC), les composants clients, les histoires Storybook et les harnais de test.

[!TIP] Modèles d'implémentation : Consultez references/examples.md pour des exemples de code complets (RSC, formulaires clients, sélecteurs de langue, décorateurs Storybook et wrappers de test). Exécution rapide : Déléguez la validation des dictionnaires ou la synchronisation des clés à un sous-agent léger (Modèle : 'flash').

---

1. Règle zéro codage en dur

• Zéro texte codé en dur : N'écrivez jamais d'étiquettes, de placeholders ou de chaînes de secours visibles par l'utilisateur dans le JSX.
• Aucun objet fictif : Les dictionnaires fictifs dans le fichier (ex. const DEFAULT_CONTENT = {...}) sont INTERDITS.
• Synchronisation synchrone : Lors de l'ajout ou de la mise à jour de contenu d'interface, insérez des traductions authentiques dans TOUS les fichiers de langue dans messages/[locale].json (ex. messages/en.json et messages/fa.json) avant d'écrire le JSX.

---

2. Guide de référence rapide des API et hooks

Environnement / Cible	Hook / API	Exemple de syntaxe
Composant serveur (RSC)	getTranslations	const t = await getTranslations('namespace');
Formateur serveur	getFormatter	const format = await getFormatter(); format.dateTime(...)
Métadonnées dynamiques	getTranslations	export async function generateMetadata({ params }) { ... }
Composant client	useTranslations	const t = useTranslations('namespace');
Formateur client	useFormatter	const format = useFormatter(); format.number(...)
Texte enrichi (client)	t.rich	t.rich('terms', { link: (c) => <Link href="/t">{c}</Link> })
Navigation	@/i18n/navigation	import { Link, useRouter, usePathname } from '@/i18n/navigation';
Aperçu Storybook	NextIntlClientProvider	Envelopper le décorateur d'aperçu avec <NextIntlClientProvider locale="en" messages={enMessages}>
Test unitaire (Jest)	renderWithIntl	Envelopper le rendu avec <NextIntlClientProvider locale="en" messages={messages}>

---

3. Normes BiDi (LTR / RTL) et de style

1. Propriétés logiques Tailwind uniquement :
   • Interdit : ml-*, mr-*, pl-*, pr-*, left-*, right-*, text-left, text-right
   • Requis : ms-*, me-*, ps-*, pe-*, start-*, end-*, text-start, text-end
2. Direction dynamique : <html dir="rtl"> dynamique pour fa/ar et dir="ltr" pour en.

---

4. Anti-patrons et pièges

Erreur	Cause racine	Solution
useTranslations dans RSC	Les hooks ne peuvent pas s'exécuter dans les composants serveur asynchrones	Utilisez await getTranslations('ns')
getTranslations dans Client	Fonction asynchrone réservée au serveur	Utilisez useTranslations('ns') avec "use client"
"Aucun contexte intl trouvé"	Fournisseur manquant dans Storybook/test	Enveloppez l'histoire/test dans <NextIntlClientProvider>
Textes de secours codés en dur	ex. `t('btn')
next/link brut	Supprime le préfixe de langue lors du changement de route	Utilisez Link depuis @/i18n/navigation

---

5. Vérification de parité

Exécutez la vérification de parité des dictionnaires :

pwsh .agents/skills/nextjs-i18n-usage/scripts/verify-dictionaries.ps1