Internationalization

NEXTDEVKIT includes a comprehensive internationalization system built with next-intl, providing automatic routing, message merging, locale detection, and seamless multi-language support for your application.

🏗️ I18n System Architecture

NEXTDEVKIT's internationalization system is structured as follows:

src/
├── i18n/
│   ├── messages.ts             # Message loading and merging
│   ├── navigation.ts           # Localized navigation
│   ├── routing.ts              # Routing configuration
│   ├── request.ts              # Request configuration
│   └── lib/
│       ├── locale-cookie.ts    # Locale cookie management
│       └── update-locale.ts    # Locale update utilities
├── messages/
│   ├── en.json                 # English translations
│   └── zh.json                 # Chinese translations
├── config/
│   └── index.ts                # I18n configuration
├── app/
│   └── [locale]/               # Locale-based routing
│       ├── layout.tsx          # Localized layouts
│       └── ...                 # Localized pages
└── middleware.ts               # Locale middleware

⚙️ I18n Configuration

App Configuration

Internationalization settings are configured in src/config/index.ts:

export const appConfig = {
  i18n: {
    enabled: true,                    // Enable/disable i18n
    defaultLocale: "en",              // Default locale
    locales: {                        // Available locales
      en: { name: "English" },
      zh: { name: "简体中文" },
    },
    localeCookieName: "NEXT_LOCALE",  // Cookie name for locale
  },
  // ... other config
} as const;

📝 Translation Messages

Message Structure

Translation messages are organized in JSON files in the messages/ directory:

English (messages/en.json):

{
  "auth": {
    "login": "Log In",
    "signup": "Sign Up",
    "logout": "Log Out",
    "email": "Email",
    "password": "Password",
    "confirmPassword": "Confirm Password",
    "forgotPassword": "Forgot Password?",
    "rememberMe": "Remember Me",
    "loginSuccess": "Login successful",
    "loginError": "Login failed"
  },
}

Chinese (messages/zh.json):

{
  "auth": {
    "login": "登录",
    "signup": "注册",
    "logout": "退出",
    "email": "邮箱",
    "password": "密码",
    "confirmPassword": "确认密码",
    "forgotPassword": "忘记密码？",
    "rememberMe": "记住我",
    "loginSuccess": "登录成功",
    "loginError": "登录失败"
  },
}

🎯 Using Translations

In Server Components

src/app/[locale]/page.tsx

import { getTranslations } from "next-intl/server";

export default async function HomePage() {
  const t = await getTranslations("Common");

  return (
    <div>
      <h1>{t("welcome")}</h1>
      <p>{t("loading")}</p>
    </div>
  );
}

In Client Components

src/components/login-form.tsx

"use client";

export function LoginForm() {
  const t = useTranslations("Authentication");

  return (
    <form>
      <Input type="email" placeholder={t("email")} />
      <Input type="password" placeholder={t("password")} />
      <Button type="submit">{t("login")}</Button>
    </form>
  );
}

NEXTDEVKIT provides localized navigation components:

import { routing } from "@/i18n/routing";
import { createNavigation } from "next-intl/navigation";

export const { Link, redirect, usePathname, useRouter, getPathname } =
  createNavigation(routing);

Using Localized Links

import { Link } from "@/i18n/navigation";
import { useTranslations } from "next-intl";

export function Header() {
  const t = useTranslations("Navigation");

  return (
    <nav>
      <Link href="/">{t("home")}</Link>
      <Link href="/about">{t("about")}</Link>
      <Link href="/contact">{t("contact")}</Link>
      <Link href="/dashboard">{t("dashboard")}</Link>
    </nav>
  );
}

🔧 Adding New Languages

1. Add Translation File

Create a new translation file in the messages/ directory:

// messages/es.json
{
  "Common": {
    "loading": "Cargando...",
    "error": "Error",
    "success": "Éxito",
    "cancel": "Cancelar",
    "save": "Guardar"
  },
  "Navigation": {
    "home": "Inicio",
    "about": "Acerca de",
    "contact": "Contacto"
  }
}

2. Update Configuration

export const appConfig = {
  i18n: {
    enabled: true,
    defaultLocale: "en",
    locales: {
      en: { name: "English" },
      zh: { name: "简体中文" },
      es: { name: "Español" }, // Add Spanish
    },
    localeCookieName: "NEXT_LOCALE",
  },
  // ... other config
} as const;

3. Update Type Definitions

export type Locale = "en" | "zh" | "es";

🔧 Troubleshooting

Common Issues

Missing Translations:

Check translation key exists in message files
Verify namespace is correct
Ensure proper fallback configuration

Locale Not Switching:

Check middleware configuration
Verify cookie settings
Ensure proper routing setup

Build Errors:

Validate JSON syntax in message files
Check type definitions
Verify locale configuration

Hydration Errors:

Ensure server and client locale match
Check cookie settings
Verify SSR configuration

🎯 Next Steps

Now that you understand the internationalization system, explore these related features: