使用Intlayer在Next.js 15中实现国际化(i18n)的完整指南

2025-06-12 16:56:25作者：盛欣凯Ernestine

前言

在现代Web开发中，国际化(i18n)已成为构建全球化应用的关键需求。Intlayer作为一个专为Next.js设计的国际化解决方案，为开发者提供了简单高效的国际化工具链。本文将详细介绍如何在Next.js 15应用中使用Intlayer实现国际化支持。

Intlayer核心优势

Intlayer区别于传统国际化方案的主要特点包括：

组件级国际化管理：允许在每个组件旁直接定义多语言内容
全栈支持：无缝支持Next.js的Server Components和Client Components
类型安全：自动生成TypeScript类型定义，提升开发体验
高性能：与Turbopack兼容，优化构建性能
动态路由支持：完美适配Next.js 15的App Router架构

环境准备

在开始前，请确保：

已安装Node.js 18+
已创建Next.js 15项目
了解基本的React和Next.js概念

安装与配置

第一步：安装依赖

根据你的包管理器选择以下命令之一：

npm install intlayer next-intlayer
# 或
yarn add intlayer next-intlayer
# 或
pnpm add intlayer next-intlayer

第二步：创建配置文件

在项目根目录创建intlayer.config.ts：

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalisation: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

第三步：集成到Next.js配置

修改next.config.js：

const { withIntlayer } = require("next-intlayer/server");

module.exports = withIntlayer({
  // 你的Next.js配置
});

项目结构改造

路由布局调整

简化根布局app/layout.tsx：

import "./globals.css";

export default function RootLayout({ children }) {
  return children;
}

创建本地化布局app/[locale]/layout.tsx：

import { NextLayoutIntlayer } from "next-intlayer";
import { getHTMLTextDir } from "intlayer";

export const generateStaticParams = () => {
  return [{ locale: "en" }, { locale: "fr" }, { locale: "es" }];
};

export default function LocaleLayout({
  children,
  params: { locale },
}: NextLayoutIntlayer) {
  return (
    <html lang={locale} dir={getHTMLTextDir(locale)}>
      <body>{children}</body>
    </html>
  );
}

内容管理实践

创建内容声明文件

在组件旁创建.content.ts文件：

// src/components/Header.content.ts
import { t, type Dictionary } from "intlayer";

export default {
  key: "header",
  content: {
    title: t({
      en: "Welcome to our site",
      fr: "Bienvenue sur notre site",
      es: "Bienvenido a nuestro sitio",
    }),
    description: t({
      en: "Discover amazing features",
      fr: "Découvrez des fonctionnalités incroyables",
      es: "Descubre características increíbles",
    }),
  },
} satisfies Dictionary;

在组件中使用内容

服务端组件示例

// src/components/ServerHeader.tsx
import { useIntlayer } from "next-intlayer/server";

export function ServerHeader() {
  const { title, description } = useIntlayer("header");
  
  return (
    <header>
      <h1>{title}</h1>
      <p>{description}</p>
    </header>
  );
}

客户端组件示例

// src/components/ClientHeader.tsx
"use client";

import { useIntlayer } from "next-intlayer";

export function ClientHeader() {
  const { title, description } = useIntlayer("header");
  
  return (
    <header>
      <h1>{title}</h1>
      <p>{description}</p>
    </header>
  );
}

高级功能实现

动态语言切换

创建语言切换组件：

"use client";

import { useRouter } from "next/navigation";
import { useIntlayer } from "next-intlayer";

export function LanguageSwitcher() {
  const router = useRouter();
  const { locales } = useIntlayer("config");

  const changeLanguage = (locale: string) => {
    // 这里实现语言切换逻辑
    router.push(`/${locale}`);
  };

  return (
    <select onChange={(e) => changeLanguage(e.target.value)}>
      {locales.map((locale) => (
        <option key={locale} value={locale}>
          {locale.toUpperCase()}
        </option>
      ))}
    </select>
  );
}

元数据国际化

在页面中实现动态元数据：

// src/app/[locale]/page.tsx
import type { Metadata } from "next";
import { getIntlayerMetadata } from "next-intlayer/server";

export async function generateMetadata({
  params: { locale },
}: {
  params: { locale: string };
}): Promise<Metadata> {
  return getIntlayerMetadata(locale, "page-metadata");
}