国际化

Codofly Template 使用 next-intl 提供完整的国际化支持，目前支持英文和简体中文。

next-intl 配置

基础配置

i18n.ts

import { notFound } from 'next/navigation'
import { getRequestConfig } from 'next-intl/server'

// 支持的语言列表
export const locales = ['en', 'zh'] as const
export type Locale = typeof locales[number]

export default getRequestConfig(async ({ locale }) => {
  // 验证语言是否支持
  if (!locales.includes(locale as any)) notFound()

  return {
    messages: (await import(`./messages/${locale}.json`)).default
  }
})

中间件配置

middleware.ts

import createMiddleware from 'next-intl/middleware'
import { locales } from './i18n'

export default createMiddleware({
  locales,
  defaultLocale: 'en',
  localePrefix: 'always'
})

export const config = {
  matcher: ['/((?!api|_next|_vercel|.*\\..*).*)']
}

翻译文件管理

英文翻译

messages/en.json

{
  "Common": {
    "save": "Save",
    "cancel": "Cancel",
    "delete": "Delete",
    "edit": "Edit",
    "loading": "Loading...",
    "error": "An error occurred"
  },
  "Navigation": {
    "home": "Home",
    "dashboard": "Dashboard",
    "teams": "Teams",
    "settings": "Settings",
    "signIn": "Sign In",
    "signOut": "Sign Out"
  },
  "HomePage": {
    "title": "Build AI SaaS Apps Fast",
    "subtitle": "Everything you need to launch your AI-powered SaaS",
    "getStarted": "Get Started",
    "learnMore": "Learn More"
  },
  "Features": {
    "ai": {
      "title": "Multi-AI Integration",
      "description": "Support for OpenAI, Anthropic, and Google models"
    },
    "auth": {
      "title": "User Authentication",
      "description": "Complete auth system with social login"
    },
    "teams": {
      "title": "Team Collaboration",
      "description": "Built-in team management and sharing"
    }
  }
}

中文翻译

messages/zh.json

{
  "Common": {
    "save": "保存",
    "cancel": "取消",
    "delete": "删除",
    "edit": "编辑",
    "loading": "加载中...",
    "error": "发生错误"
  },
  "Navigation": {
    "home": "首页",
    "dashboard": "仪表盘",
    "teams": "团队",
    "settings": "设置",
    "signIn": "登录",
    "signOut": "退出"
  },
  "HomePage": {
    "title": "快速构建 AI SaaS 应用",
    "subtitle": "启动 AI 驱动的 SaaS 所需的一切",
    "getStarted": "开始使用",
    "learnMore": "了解更多"
  },
  "Features": {
    "ai": {
      "title": "多 AI 模型集成",
      "description": "支持 OpenAI、Anthropic 和 Google 模型"
    },
    "auth": {
      "title": "用户认证",
      "description": "完整的认证系统，支持社交登录"
    },
    "teams": {
      "title": "团队协作",
      "description": "内置团队管理和共享功能"
    }
  }
}

多语言路由

根布局

app/[locale]/layout.tsx

import { NextIntlClientProvider } from 'next-intl'
import { getMessages } from 'next-intl/server'
import { setRequestLocale } from 'next-intl/server'
import { locales } from '@/i18n'

export function generateStaticParams() {
  return locales.map((locale) => ({ locale }))
}

interface Props {
  children: React.ReactNode
  params: { locale: string }
}

export default async function LocaleLayout({
  children,
  params: { locale }
}: Props) {
  // 启用静态渲染
  setRequestLocale(locale)
  
  const messages = await getMessages()

  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  )
}

页面国际化

app/[locale]/page.tsx

import { useTranslations } from 'next-intl'
import { setRequestLocale } from 'next-intl/server'

interface Props {
  params: { locale: string }
}

export default function HomePage({ params: { locale } }: Props) {
  setRequestLocale(locale)
  
  const t = useTranslations('HomePage')

  return (
    <div className="text-center">
      <h1 className="text-4xl font-bold">{t('title')}</h1>
      <p className="text-xl text-gray-600 mt-4">{t('subtitle')}</p>
      <div className="mt-8 space-x-4">
        <button className="bg-blue-500 text-white px-6 py-2 rounded">
          {t('getStarted')}
        </button>
        <button className="border border-gray-300 px-6 py-2 rounded">
          {t('learnMore')}
        </button>
      </div>
    </div>
  )
}

语言切换

语言切换组件

components/language-switcher.tsx

'use client'

import { useLocale } from 'next-intl'
import { usePathname, useRouter } from 'next/navigation'
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'

const languages = [
  { code: 'en', name: 'English', flag: '🇺🇸' },
  { code: 'zh', name: '简体中文', flag: '🇨🇳' }
]

export function LanguageSwitcher() {
  const locale = useLocale()
  const router = useRouter()
  const pathname = usePathname()

  const handleLanguageChange = (newLocale: string) => {
    // 移除当前语言前缀
    const pathWithoutLocale = pathname.replace(`/${locale}`, '') || '/'
    
    // 添加新语言前缀
    const newPath = `/${newLocale}${pathWithoutLocale}`
    
    router.push(newPath)
  }

  return (
    <Select value={locale} onValueChange={handleLanguageChange}>
      <SelectTrigger className="w-40">
        <SelectValue>
          {languages.find(lang => lang.code === locale)?.flag}{' '}
          {languages.find(lang => lang.code === locale)?.name}
        </SelectValue>
      </SelectTrigger>
      <SelectContent>
        {languages.map(language => (
          <SelectItem key={language.code} value={language.code}>
            {language.flag} {language.name}
          </SelectItem>
        ))}
      </SelectContent>
    </Select>
  )
}

导航栏集成

components/navbar.tsx

import { useTranslations } from 'next-intl'
import { LanguageSwitcher } from './language-switcher'
import { Link } from '@/navigation'

export function Navbar() {
  const t = useTranslations('Navigation')

  return (
    <nav className="flex items-center justify-between p-4">
      <div className="flex space-x-6">
        <Link href="/">{t('home')}</Link>
        <Link href="/dashboard">{t('dashboard')}</Link>
        <Link href="/teams">{t('teams')}</Link>
      </div>
      
      <div className="flex items-center space-x-4">
        <LanguageSwitcher />
        <Link href="/auth/signin">{t('signIn')}</Link>
      </div>
    </nav>
  )
}

内容本地化

日期和时间

lib/date-formatter.ts

import { useLocale } from 'next-intl'

export function useDateFormatter() {
  const locale = useLocale()

  const formatDate = (date: Date) => {
    return new Intl.DateTimeFormat(locale, {
      year: 'numeric',
      month: 'long',
      day: 'numeric'
    }).format(date)
  }

  const formatDateTime = (date: Date) => {
    return new Intl.DateTimeFormat(locale, {
      year: 'numeric',
      month: 'short',
      day: 'numeric',
      hour: '2-digit',
      minute: '2-digit'
    }).format(date)
  }

  return { formatDate, formatDateTime }
}

数字格式化

components/price-display.tsx

import { useLocale } from 'next-intl'

interface PriceDisplayProps {
  amount: number
  currency?: string
}

export function PriceDisplay({ amount, currency = 'USD' }: PriceDisplayProps) {
  const locale = useLocale()

  const formatPrice = (amount: number, currency: string) => {
    return new Intl.NumberFormat(locale, {
      style: 'currency',
      currency: currency
    }).format(amount)
  }

  return <span>{formatPrice(amount, currency)}</span>
}

复数处理

components/message-count.tsx

import { useTranslations } from 'next-intl'

interface MessageCountProps {
  count: number
}

export function MessageCount({ count }: MessageCountProps) {
  const t = useTranslations('Messages')

  return (
    <span>
      {t('count', { count })}
    </span>
  )
}

对应的翻译文件：

{
  "Messages": {
    "count": {
      "0": "No messages",
      "1": "1 message", 
      "other": "{count} messages"
    }
  }
}

动态导入翻译

按需加载翻译

lib/translations.ts

export async function loadTranslations(locale: string, namespace: string) {
  try {
    const messages = await import(`@/messages/${locale}/${namespace}.json`)
    return messages.default
  } catch (error) {
    console.warn(`Failed to load ${namespace} translations for ${locale}`)
    return {}
  }
}

分离翻译文件

messages/
├── en/
│   ├── common.json
│   ├── navigation.json
│   ├── auth.json
│   └── dashboard.json
└── zh/
    ├── common.json
    ├── navigation.json
    ├── auth.json
    └── dashboard.json

添加新语言

步骤

添加语言到配置

i18n.ts

export const locales = ['en', 'zh', 'ja'] as const // 添加日语

创建翻译文件

messages/ja.json

{
  "Common": {
    "save": "保存",
    "cancel": "キャンセル",
    "delete": "削除"
  }
}

更新语言切换器

components/language-switcher.tsx

const languages = [
  { code: 'en', name: 'English', flag: '🇺🇸' },
  { code: 'zh', name: '简体中文', flag: '🇨🇳' },
  { code: 'ja', name: '日本語', flag: '🇯🇵' } // 添加日语
]

服务端组件翻译

API 响应本地化

app/api/messages/route.ts

import { getTranslations } from 'next-intl/server'

export async function POST(request: Request) {
  const { locale } = await request.json()
  const t = await getTranslations({ locale, namespace: 'API' })

  try {
    // 处理逻辑
    return NextResponse.json({
      message: t('success')
    })
  } catch (error) {
    return NextResponse.json({
      error: t('error')
    }, { status: 500 })
  }
}

最佳实践

1. 翻译键命名

// ✅ 好的命名
"Auth.SignIn.title"
"Dashboard.Stats.users"
"Teams.Members.invite"

// ❌ 避免的命名
"text1"
"message"
"button"

2. 翻译文件结构

{
  "ComponentName": {
    "title": "标题",
    "description": "描述",
    "actions": {
      "save": "保存",
      "cancel": "取消"
    }
  }
}

3. 处理缺失翻译

lib/fallback-translations.ts

export function withFallback(key: string, fallback: string) {
  const t = useTranslations()
  
  try {
    return t(key)
  } catch {
    return fallback
  }
}

建议使用专业翻译工具如 Crowdin 或 Lokalise 来管理大型项目的翻译工作。

性能优化

翻译预加载

app/[locale]/loading.tsx

import { getMessages } from 'next-intl/server'

export default async function Loading({ params: { locale } }) {
  // 预加载翻译
  await getMessages()
  
  return <div>Loading...</div>
}

静态生成

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    ppr: true, // 启用部分预渲染
  },
}

module.exports = nextConfig

查看 next-intl 文档了解更多高级功能。

开始使用

开发教程

功能特性

国际化

国际化

next-intl 配置

基础配置

中间件配置

翻译文件管理

英文翻译

中文翻译

多语言路由

根布局

页面国际化

语言切换

语言切换组件

导航栏集成

内容本地化

日期和时间

数字格式化

复数处理

动态导入翻译

按需加载翻译

分离翻译文件

添加新语言

步骤

服务端组件翻译

API 响应本地化

最佳实践

1. 翻译键命名

2. 翻译文件结构

3. 处理缺失翻译

性能优化

翻译预加载

静态生成

​国际化

​next-intl 配置

​基础配置

​中间件配置

​翻译文件管理

​英文翻译

​中文翻译

​多语言路由

​根布局

​页面国际化

​语言切换

​语言切换组件

​导航栏集成

​内容本地化

​日期和时间

​数字格式化

​复数处理

​动态导入翻译

​按需加载翻译

​分离翻译文件

​添加新语言

​步骤

​服务端组件翻译

​API 响应本地化

​最佳实践

​1. 翻译键命名

​2. 翻译文件结构

​3. 处理缺失翻译

​性能优化

​翻译预加载

​静态生成

国际化

next-intl 配置

基础配置

中间件配置

翻译文件管理

英文翻译

中文翻译

多语言路由

根布局

页面国际化

语言切换

语言切换组件

导航栏集成

内容本地化

日期和时间

数字格式化

复数处理

动态导入翻译

按需加载翻译

分离翻译文件

添加新语言

步骤

服务端组件翻译

API 响应本地化

最佳实践

1. 翻译键命名

2. 翻译文件结构

3. 处理缺失翻译

性能优化

翻译预加载

静态生成