Next.js 15集成i18next SSR时Hydration失败问题及适配方案咨询

你的Hydration失败问题核心原因是服务端与客户端渲染时使用的语言环境或翻译内容不一致，以下是针对Next.js 15 App Router + React 18的SSR兼容i18n配置步骤：

1. 编写通用i18n配置（区分服务端/客户端） #

创建src/i18n.ts文件，通过环境判断区分服务端和客户端的初始化逻辑，避免服务端调用浏览器API：

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import Backend from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';
import enTranslation from '@/public/locales/en.json';
import zhTranslation from '@/public/locales/zh.json';

// 服务端直接同步加载翻译文件，客户端用HTTP Backend加载
const resources = {
  en: { translation: enTranslation },
  zh: { translation: zhTranslation },
};

export async function initI18n(language: string = 'en') {
  const instance = i18n.createInstance();
  
  await instance
    .use(initReactI18next)
    // 服务端禁用浏览器Detector和HTTP Backend
    .use(typeof window !== 'undefined' ? Backend : null)
    .use(typeof window !== 'undefined' ? LanguageDetector : null)
    .init({
      resources: typeof window === 'undefined' ? resources : undefined,
      lng: language,
      fallbackLng: 'en',
      interpolation: { escapeValue: false },
      // 服务端禁用缓存，避免请求间污染
      cache: typeof window !== 'undefined' ? undefined : { enabled: false },
    });

  return instance;
}

2. 在Root Layout中注入服务端语言上下文 #

在src/app/layout.tsx中，通过headers()获取请求头中的语言信息，初始化i18n实例并传递给组件树：

import { ReactNode } from 'react';
import { initI18n } from '@/i18n';
import { I18nextProvider } from 'react-i18next';

export default async function RootLayout({ children }: { children: ReactNode }) {
  // 从请求头获取用户语言（也可从URL参数、Cookie中读取）
  const headers = await headers();
  const userLanguage = headers.get('accept-language')?.split(',')[0] || 'en';
  
  // 初始化服务端i18n实例
  const i18nInstance = await initI18n(userLanguage);

  return (
    <html lang={userLanguage}>
      <body>
        <I18nextProvider i18n={i18nInstance}>
          {children}
        </I18nextProvider>
      </body>
    </html>
  );
}

3. 组件中正确使用翻译 #

客户端组件 #

标记为客户端组件后，直接使用useTranslation钩子：

'use client';

import { useTranslation } from 'react-i18next';

export default function HomePage() {
  const { t } = useTranslation();
  
  return (
    <div>
      <h1>{t('welcome.title')}</h1>
      <p>{t('welcome.description')}</p>
    </div>
  );
}

服务器组件 #

服务器组件不能直接使用客户端钩子，需手动初始化i18n实例并调用翻译函数：

import { initI18n } from '@/i18n';

export default async function ServerComponent() {
  const headers = await headers();
  const userLanguage = headers.get('accept-language')?.split(',')[0] || 'en';
  const i18nInstance = await initI18n(userLanguage);
  
  return <h1>{i18nInstance.t('welcome.title')}</h1>;
}

4. 排查Hydration不匹配的额外技巧 #

• 检查翻译文件：确保public/locales下各语言文件的键名完全一致，无遗漏或拼写错误
• 强制客户端语言对齐：客户端初始化时强制使用服务端传递的语言，避免自动检测导致的环境不一致
• 对比渲染内容：查看浏览器页面源代码（服务端HTML）和客户端渲染后的DOM，定位具体不匹配的翻译节点

内容的提问来源于stack exchange，提问作者Seda Babir