Next.js使用next-translate切换非英语语言刷新时遇Hydration错误

问题根源 #

服务端渲染时无法读取localStorage，会默认使用i18n.js中配置的en语言；而客户端Hydrate时会读取localStorage中存储的自定义语言，两者渲染内容不匹配，触发Hydration错误。

解决方案：用Cookie同步服务端与客户端语言 #

服务端可以读取Cookie，因此将选中的语言存储到Cookie中，让服务端渲染时能获取到用户选中的语言，保证两端内容一致。

1. 切换语言时写入Cookie #

安装js-cookie简化Cookie操作（也可使用原生document.cookie）：

npm install js-cookie

编写切换语言的函数：

import Cookies from 'js-cookie';

export const switchLanguage = (locale) => {
  // 将语言写入Cookie，设置有效期1年，作用域为根目录
  Cookies.set('NEXT_LOCALE', locale, { expires: 365, path: '/' });
  // 同步更新localStorage（可选，兼容原有逻辑）
  localStorage.setItem('selectedLanguage', locale);
  // 刷新页面或通过路由跳转生效（根据你的路由模式选择）
  window.location.href = `/${locale}${window.location.pathname}${window.location.search}`;
};

2. 配置next-translate从Cookie读取语言 #

修改根目录i18n.js，关闭自动语言检测，添加自定义语言解析逻辑：

const Cookies = require('js-cookie');

module.exports = {
  locales: ["ar", "en","es"],
  defaultLocale: "en",
  pages: {
    "*": ["common"],
  },
  localeDetection: false, // 禁用默认语言检测
  localeResolver: (locale, req, res) => {
    // 服务端从请求Cookie中读取语言
    if (req) {
      const cookieLocale = req.cookies?.NEXT_LOCALE;
      if (cookieLocale && ["ar", "en", "es"].includes(cookieLocale)) {
        return cookieLocale;
      }
    } else {
      // 客户端优先从Cookie读取，其次是localStorage
      const cookieLocale = Cookies.get('NEXT_LOCALE');
      const storageLocale = localStorage.getItem('selectedLanguage');
      return cookieLocale || storageLocale || "en";
    }
    return "en";
  },
};

3. 验证效果 #

切换非英语语言后刷新页面，服务端会从Cookie中读取选中的语言进行渲染，客户端Hydrate时内容与服务端完全一致，不会再触发Hydration错误，同时能维持用户选中的语言状态。

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