Next.js App Router + next-intl Complete Skill

1. Directory Structure & File Placement

• Root Directory (src/app/):
  • page.tsx: Handles root redirects if middleware is bypassed or static export is used. MUST redirect to default locale (/tr).
  • not-found.tsx: Global catch-all 404 page for unmatched routes outside any locale context (e.g., /unknown.txt).
  • middleware.ts: Handles dynamic locale detection and routing at the edge.
• Locale Directory (src/app/[locale]/):
  • All localized pages MUST live inside src/app/[locale]/.
  • layout.tsx: Root localized layout. Configures html lang and dir (RTL/LTR).
  • page.tsx: Main localized entry page.
  • error.tsx & not-found.tsx: Must reside inside [locale] to retain language and RTL context during error states.
  • [...rest]/page.tsx: Catch-all route to handle invalid paths inside a locale and trigger notFound().

2. Root Redirects & Catch-All Page Rules

src/app/page.tsx (Root Page)

import { redirect } from 'next/navigation';

// Executed as fallback for static export or direct root access
export default function RootPage() {
  redirect('/tr'); // Default locale is 'tr'
}

src/app/not-found.tsx (Global 404 Page)

'use client';

import Error from 'next/error';

// Renders when a non-localized route (e.g. `/unknown.txt`) is requested,
// or when root layout validation fails before entering `[locale]`.
export default function GlobalNotFound() {
  return (
    <html lang="en">
      <body>
        <Error statusCode="{404}"/>
      </body>
    </html>
  );
}

src/app/[locale]/[...rest]/page.tsx (Unmatched Route Handler)

import { notFound } from 'next/navigation';

export default function CatchAllPage() {
  notFound();
}

3. Root Layout (src/app/[locale]/layout.tsx) & RTL Support

• MUST extract locale from params (handle async params in Next.js 15+).
• MUST validate locale against supported list (['tr', 'en', 'ar']) using notFound() if invalid.
• MUST dynamically set <html lang={locale} dir={isRtlLocale(locale) ? 'rtl' : 'ltr'}> (e.g., set dir="rtl" for RTL languages like Arabic, Hebrew, Persian, or Urdu).
• MUST wrap the layout with NextIntlClientProvider using messages retrieved via getMessages() from next-intl/server.

4. RTL & Tailwind Logical Properties

• MUST use Tailwind CSS Logical Properties for alignment to prevent broken layouts when switching between LTR and RTL languages (e.g., Arabic, Hebrew):
  • Margins: ms-* / me-* (instead of ml-* / mr-*)
  • Padding: ps-* / pe-* (instead of pl-* / pr-*)
  • Positioning: start-* / end-* (instead of left-* / right-*)

5. Navigation & Data Patterns

• MUST import Link, redirect, useRouter, and usePathname from @/i18n/navigation (or next-intl/navigation), NEVER directly from next/link or next/navigation.
• Data fetching logic MUST be isolated in src/lib/data.ts. Server Components should call data functions directly without internal HTTP fetch().