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

2025-06-12 08:05:26作者：昌雅子Ethen

前言

在现代Web应用开发中，国际化(i18n)已成为必不可少的功能。Intlayer作为一个专为Next.js设计的国际化解决方案，提供了简单高效的实现方式。本文将详细介绍如何在Next.js 15应用中使用Intlayer实现国际化功能。

Intlayer简介

Intlayer是一个专为现代Web应用设计的国际化库，具有以下核心特点：

组件级声明式字典管理
支持动态本地化元数据、路由和内容
同时支持客户端和服务器组件
完整的TypeScript支持
高级功能如动态语言检测和切换

环境准备

安装依赖

首先需要安装Intlayer核心包和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 = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

此配置定义了应用支持的语言和默认语言。

修改Next.js配置

更新next.config.js以集成Intlayer：

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

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 其他Next.js配置
};

module.exports = withIntlayer(nextConfig);

路由与布局配置

设置根布局

简化根布局文件app/layout.tsx：

import "./globals.css";

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

创建语言布局

在app/[locale]目录下创建语言布局：

import { getHTMLTextDir } from "intlayer";
import { Inter } from "next/font/google";

const inter = Inter({ subsets: ["latin"] });

export { generateStaticParams } from "next-intlayer";

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

内容管理

创建内容字典

在组件同级目录创建.content.ts文件定义多语言内容：

import { t, type Dictionary } from "intlayer";

const pageContent = {
  key: "page",
  content: {
    getStarted: {
      main: t({
        en: "Get started by editing",
        fr: "Commencez par éditer",
        es: "Comience por editar",
      }),
      pageLink: "src/app/page.tsx",
    },
  },
} satisfies Dictionary;

export default pageContent;

在组件中使用

服务器组件示例

import { useIntlayer } from "next-intlayer/server";

export function ServerComponentExample() {
  const content = useIntlayer("server-component-example");
  
  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
}

客户端组件示例

"use client";

import { useIntlayer } from "next-intlayer";

export function ClientComponentExample() {
  const content = useIntlayer("client-component-example");
  
  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
}

高级配置

语言检测中间件

创建middleware.ts实现自动语言检测：

export { intlayerMiddleware as middleware } from "next-intlayer/middleware";

export const config = {
  matcher: "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
};

国际化元数据

在布局或页面中使用generateMetadata实现国际化元数据：

import { getTranslation } from "next-intlayer/server";

export async function generateMetadata({ params }) {
  const t = await getTranslation(params.locale, "metadata");
  
  return {
    title: t("title"),
    description: t("description"),
  };
}