Internationalization

Copyimport { getDictionary } from "@/components/local/dictionaries";
import type { Locale } from "@/components/local/config";
 
export default async function Page({ params }: { params: { lang: string } }) {
  const dictionary = await getDictionary(params.lang as Locale);
 
  return (
    <div>
      <h1>{dictionary.common.home}</h1>
      <p>{dictionary.common.loading}</p>
    </div>
  );
}

Copy"use client";
import { useLocale } from "@/components/local/use-locale";
 
export function LocaleIndicator() {
  const { locale, isRTL, localeConfig } = useLocale();
 
  return (
    <span className={isRTL ? "text-right" : "text-left"}>
      {localeConfig.flag} {localeConfig.nativeName}
    </span>
  );
}

Copyexport const i18n = {
  defaultLocale: 'en',
  locales: ['en', 'ar'],
} as const;
 
export type Locale = (typeof i18n)['locales'][number];
 
export const localeConfig = {
  'en': {
    name: 'English',
    nativeName: 'English',
    dir: 'ltr',
    flag: 'US',
    dateFormat: 'MM/dd/yyyy',
    currency: 'USD',
  },
  'ar': {
    name: 'Arabic',
    nativeName: 'Arabic',
    dir: 'rtl',
    flag: 'SA',
    dateFormat: 'dd/MM/yyyy',
    currency: 'SAR',
  },
} as const;
 
export function isRTL(locale: Locale): boolean {
  return localeConfig[locale]?.dir === 'rtl';
}

Copyimport "server-only";
import type { Locale } from "./config";
 
const dictionaries = {
  "en": () => import("./en.json").then((module) => module.default),
  "ar": () => import("./ar.json").then((module) => module.default),
} as const;
 
export const getDictionary = async (locale: Locale) => {
  try {
    return await (dictionaries[locale]?.() ?? dictionaries["en"]());
  } catch (error) {
    console.warn(`Failed to load dictionary for locale: ${locale}`);
    return await dictionaries["en"]();
  }
};
 
export type Dictionary = Awaited<ReturnType<typeof getDictionary>>;

Copy{
  "metadata": {
    "title": "App Title",
    "description": "App Description"
  },
  "common": {
    "loading": "Loading...",
    "home": "Home",
    "language": "Language"
  },
  "navigation": {
    "docs": "Docs",
    "atoms": "Atoms"
  }
}

Copyimport type { Dictionary } from "@/components/local/dictionaries";
 
interface Props {
  dictionary: Dictionary;
}
 
export function Header({ dictionary }: Props) {
  return <nav>{dictionary.navigation.docs}</nav>;
}

Copyimport { match } from '@formatjs/intl-localematcher';
import Negotiator from 'negotiator';
import { type NextRequest, NextResponse } from 'next/server';
import { i18n } from './config';
 
function getLocale(request: NextRequest) {
  // 1. Check cookie first
  const cookieLocale = request.cookies.get('NEXT_LOCALE')?.value;
  if (cookieLocale && i18n.locales.includes(cookieLocale as any)) {
    return cookieLocale;
  }
 
  // 2. Parse Accept-Language header
  const headers = {
    'accept-language': request.headers.get('accept-language') ?? '',
  };
  const languages = new Negotiator({ headers }).languages();
 
  // 3. Match against supported locales
  return match(languages, i18n.locales, i18n.defaultLocale);
}
 
export function localizationMiddleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
 
  // Check if pathname already has a locale
  const pathnameHasLocale = i18n.locales.some(
    (locale) => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
  );
 
  if (pathnameHasLocale) return NextResponse.next();
 
  // Redirect to localized URL
  const locale = getLocale(request);
  request.nextUrl.pathname = `/${locale}${pathname}`;
 
  const response = NextResponse.redirect(request.nextUrl);
  response.cookies.set('NEXT_LOCALE', locale, {
    maxAge: 365 * 24 * 60 * 60, // 1 year
    sameSite: 'lax',
    secure: process.env.NODE_ENV === 'production',
  });
 
  return response;
}

Copypnpm add @formatjs/intl-localematcher negotiator
pnpm add -D @types/negotiator

Copy"use client";
import { useLocale } from "@/components/local/use-locale";
 
export function MyComponent() {
  const { locale, isRTL, localeConfig } = useLocale();
 
  return (
    <div dir={isRTL ? 'rtl' : 'ltr'}>
      <p>Current: {localeConfig.nativeName}</p>
      <p>Direction: {localeConfig.dir}</p>
      <p>Currency: {localeConfig.currency}</p>
    </div>
  );
}

Copy"use client";
import { useSwitchLocaleHref } from "@/components/local/use-locale";
import { i18n, localeConfig } from "@/components/local/config";
import Link from "next/link";
 
export function LanguageSwitcher() {
  const switchLocaleHref = useSwitchLocaleHref();
 
  return (
    <nav className="flex gap-2">
      {i18n.locales.map((locale) => (
        <Link key={locale} href={switchLocaleHref(locale)}>
          {localeConfig[locale].flag} {localeConfig[locale].nativeName}
        </Link>
      ))}
    </nav>
  );
}

Copy// src/app/[lang]/layout.tsx
import { localeConfig, type Locale } from "@/components/local/config";
 
export default async function RootLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: { lang: string };
}) {
  const { lang } = await params as { lang: Locale };
  const config = localeConfig[lang];
 
  return (
    <html lang={lang} dir={config.dir}>
      <body>{children}</body>
    </html>
  );
}

Copy/* Instead of: */
.element {
  margin-left: 1rem;
  padding-right: 2rem;
}
 
/* Use: */
.element {
  margin-inline-start: 1rem;
  padding-inline-end: 2rem;
}

Copy.layout-container {
  padding-inline: var(--container-padding);
}
 
.ps-responsive {
  padding-inline-start: var(--container-padding);
}
 
.pe-responsive {
  padding-inline-end: var(--container-padding);
}
 
.ms-responsive {
  margin-inline-start: 2rem;
}
 
.me-responsive {
  margin-inline-end: 2rem;
}

Copyimport { toArabicNumerals, toEnglishNumerals } from "@/lib/arabic-utils";
 
// Convert to Arabic-Indic numerals
toArabicNumerals("123")     // "١٢٣"
toArabicNumerals("2024")    // "٢٠٢٤"
 
// Convert back to Western numerals
toEnglishNumerals("١٢٣")    // "123"

Copyimport { formatArabicNumber, formatArabicPercentage } from "@/lib/arabic-utils";
 
// Format with Arabic thousands separators
formatArabicNumber(1234567)          // "١٬٢٣٤٬٥٦٧"
 
// Format percentage
formatArabicPercentage(75)           // "٧٥٫٠٪"
formatArabicPercentage(99.5, 2)      // "٩٩٫٥٠٪"

Copyimport { formatArabicCurrency } from "@/lib/arabic-utils";
 
formatArabicCurrency(1500)           // "١٬٥٠٠٫٠٠ ر.س"
formatArabicCurrency(99.99)          // "٩٩٫٩٩ ر.س"

Copyimport { formatArabicDate, formatArabicRelativeTime } from "@/lib/arabic-utils";
 
// Full date format
formatArabicDate(new Date())         // "٢٧ نوفمبر ٢٠٢٥"
 
// Relative time
formatArabicRelativeTime(pastDate)   // "منذ يومين"
formatArabicRelativeTime(futureDate) // "خلال ٣ أيام"

Copyimport { formatArabicFileSize } from "@/lib/arabic-utils";
 
formatArabicFileSize(1024)           // "١ كيلوبايت"
formatArabicFileSize(5242880)        // "٥٫٠ ميجابايت"
formatArabicFileSize(1073741824)     // "١٫٠ جيجابايت"

Copyimport { arabicPlural } from "@/lib/arabic-utils";
 
arabicPlural(1, "طالب", "طالبان", "طلاب")  // "طالب" (singular)
arabicPlural(2, "طالب", "طالبان", "طلاب")  // "طالبان" (dual)
arabicPlural(5, "طالب", "طالبان", "طلاب")  // "طلاب" (plural)
 
// Common examples
arabicPlural(count, "يوم", "يومان", "أيام")     // day/days
arabicPlural(count, "ملف", "ملفان", "ملفات")   // file/files
arabicPlural(count, "رسالة", "رسالتان", "رسائل") // message/messages

Copyimport { getTextDirection } from "@/lib/arabic-utils";
 
getTextDirection("Hello World")      // "ltr"
getTextDirection("مرحبا")            // "rtl"
getTextDirection("Hello مرحبا")      // "rtl" (Arabic detected)

Copyimport { getRTLClasses } from "@/lib/arabic-utils";
 
getRTLClasses(true)   // "rtl:text-right rtl:space-x-reverse rtl:ml-auto rtl:mr-0"
getRTLClasses(false)  // ""

Copyimport { ARABIC_TYPOGRAPHY_VARS, applyArabicTypography } from "@/lib/arabic-utils";
 
// CSS custom properties
ARABIC_TYPOGRAPHY_VARS = {
  '--font-arabic': '"Noto Sans Arabic", "Amiri", "Scheherazade New", sans-serif',
  '--font-arabic-display': '"Amiri", "Scheherazade New", serif',
  '--line-height-arabic': '1.8',
  '--letter-spacing-arabic': '0.02em'
}
 
// Apply to DOM element
applyArabicTypography(element);

Copyimport { isArabicLocale } from "@/lib/arabic-utils";
 
isArabicLocale("ar")     // true
isArabicLocale("ar-SA")  // true
isArabicLocale("en")     // false

Copyimport { getLocaleFormatters } from "@/lib/arabic-utils";
 
const formatters = getLocaleFormatters("ar");
 
formatters.formatNumber(1234)          // "١٬٢٣٤"
formatters.formatCurrency(99.99)       // "٩٩٫٩٩ ر.س"
formatters.formatPercentage(75)        // "٧٥٫٠٪"
formatters.formatDate(new Date())      // "٢٧ نوفمبر ٢٠٢٥"
formatters.formatRelativeTime(date)    // "منذ يومين"
formatters.isRTL                       // true
formatters.textDirection               // "rtl"
 
// English formatters
const enFormatters = getLocaleFormatters("en");
enFormatters.formatNumber(1234)        // "1,234"
enFormatters.isRTL                     // false

Copyimport { escapeArabicHTML } from "@/lib/arabic-utils";
 
// Safe for HTML rendering
escapeArabicHTML("<script>مرحبا</script>")
// "&lt;script&gt;مرحبا&lt;/script&gt;"