Next.js i18n Wörterbücher & Provider

Next.js i18n Wörterbücher & Provider (nextjs-i18n-usage)

Engineering-Standards, Hooks und Provider-Muster für die Verwendung von next-intl-Übersetzungen in React-Server-Komponenten, Client-Komponenten, Storybook-Stories und Test-Umgebungen.

[!TIP] Implementierungsmuster: Siehe references/examples.md für vollständige Codebeispiele (RSC, Client-Formulare, Sprachumschalter, Storybook-Dekoratoren und Test-Wrapper). Schnelle Ausführung: Delegieren Sie die Wörterbuchvalidierung oder Schlüsselsynchronisation an einen leichtgewichtigen Subagenten (Model: 'flash').

---

1. Kein-Hartcodierung-Vertrag

• Keine hartcodierten Texte: Schreiben Sie niemals benutzerseitige Labels, Platzhalter oder Fallback-Zeichenketten in JSX.
• Keine Mock-Objekte: Mock-Wörterbücher in der Datei (z. B. const DEFAULT_CONTENT = {...}) sind VERBOTEN.
• Synchrone Synchronisation: Fügen Sie beim Hinzufügen/Aktualisieren von UI-Texten authentische Übersetzungen in ALLE Lokalisierungsdateien unter messages/[locale].json (z. B. messages/en.json und messages/fa.json) ein, bevor Sie JSX schreiben.

---

2. API- und Hooks-Kurzreferenz

Umgebung / Ziel	Hook / API	Beispielsyntax
Server-Komponente (RSC)	getTranslations	const t = await getTranslations('namespace');
Server-Formatierer	getFormatter	const format = await getFormatter(); format.dateTime(...)
Dynamische Metadaten	getTranslations	export async function generateMetadata({ params }) { ... }
Client-Komponente	useTranslations	const t = useTranslations('namespace');
Client-Formatierer	useFormatter	const format = useFormatter(); format.number(...)
Rich-Text (Client)	t.rich	t.rich('terms', { link: (c) => <Link href="/t">{c}</Link> })
Navigation	@/i18n/navigation	import { Link, useRouter, usePathname } from '@/i18n/navigation';
Storybook-Vorschau	NextIntlClientProvider	Umfassen Sie den Preview-Dekorator mit <NextIntlClientProvider locale="en" messages={enMessages}>
Unit-Testing (Jest)	renderWithIntl	Umfassen Sie Render mit <NextIntlClientProvider locale="en" messages={messages}>

---

3. BiDi (LTR / RTL) & Styling-Standards

1. Nur Tailwind Logical Properties:
   • Verboten: ml-*, mr-*, pl-*, pr-*, left-*, right-*, text-left, text-right
   • Erforderlich: ms-*, me-*, ps-*, pe-*, start-*, end-*, text-start, text-end
2. Dynamische Richtung: Dynamisches <html dir="rtl"> für fa/ar und dir="ltr" für en.

---

4. Anti-Patterns & Fallstricke

Fehler	Ursache	Lösung
useTranslations in RSC	Hooks können nicht in asynchronen Server-Komponenten ausgeführt werden	Verwenden Sie await getTranslations('ns')
getTranslations in Client	Nur serverseitige asynchrone Funktion	Verwenden Sie useTranslations('ns') mit "use client"
"No intl context found"	Fehlender Provider in Storybook/Test	Umfassen Sie Story/Test mit <NextIntlClientProvider>
Hartcodierte Fallbacks	z. B. `t('btn')
Rohes next/link	Entfernt das Lokalisierungspräfix bei Routenwechsel	Verwenden Sie Link aus @/i18n/navigation

---

5. Paritätsprüfung

Führen Sie die Wörterbuch-Paritätsprüfung durch:

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