国际化

NEXTDEVKIT 包含一个基于 next-intl 构建的全面国际化系统，提供自动路由、消息合并、语言检测以及应用程序的无缝多语言支持。

🏗️ 国际化系统架构

NEXTDEVKIT 的国际化系统结构如下：

src/
├── i18n/
│   ├── messages.ts             # 消息加载和合并
│   ├── navigation.ts           # 本地化导航
│   ├── routing.ts              # 路由配置
│   ├── request.ts              # 请求配置
│   └── lib/
│       ├── locale-cookie.ts    # 语言 Cookie 管理
│       └── update-locale.ts    # 语言更新工具
├── messages/
│   ├── en.json                 # 英文翻译
│   └── zh.json                 # 中文翻译
├── config/
│   └── index.ts                # 国际化配置
├── app/
│   └── [locale]/               # 基于语言的路由
│       ├── layout.tsx          # 本地化布局
│       └── ...                 # 本地化页面
└── middleware.ts               # 语言中间件

⚙️ 国际化配置

应用配置

国际化设置在 src/config/index.ts 中配置：

export const appConfig = {
  i18n: {
    enabled: true,                    // 启用/禁用国际化
    defaultLocale: "en",              // 默认语言
    locales: {                        // 可用语言
      en: { name: "English" },
      zh: { name: "简体中文" },
    },
    localeCookieName: "NEXT_LOCALE",  // 语言 Cookie 名称
  },
  // ... 其他配置
} as const;

📝 翻译消息

消息结构

翻译消息在 messages/ 目录的 JSON 文件中组织：

英文（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"
  },
}

中文（messages/zh.json）：

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

🎯 使用翻译

在服务器组件中

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>
  );
}

在客户端组件中

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 提供本地化导航组件：

src/i18n/navigation.ts

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

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

使用本地化链接

src/components/header.tsx

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>
  );
}

🔧 添加新语言

1. 添加翻译文件

在 messages/ 目录中创建新的翻译文件：

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

2. 更新配置

src/config/index.ts

export const appConfig = {
  i18n: {
    enabled: true,
    defaultLocale: "en",
    locales: {
      en: { name: "English" },
      zh: { name: "简体中文" },
      es: { name: "Español" }, // 添加西班牙语
    },
    localeCookieName: "NEXT_LOCALE",
  },
  // ... 其他配置
} as const;

3. 更新类型定义

src/types/locale.ts

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

🔧 故障排除

常见问题

缺失翻译：

检查翻译键是否存在于消息文件中
验证命名空间是否正确
确保正确的回退配置

语言未切换：

检查中间件配置
验证 Cookie 设置
确保正确的路由设置

构建错误：

验证消息文件中的 JSON 语法
检查类型定义
验证语言配置

水合错误：

确保服务器和客户端语言匹配
检查 Cookie 设置
验证 SSR 配置

🔗 相关资源

🎯 下一步

现在您了解了国际化系统，请探索这些相关功能：

On this page