如何在Next.js项目中集成Tolgee与next-i18next？

我基于next-i18next搭建了一个Next.js多语言应用，现在想接入Tolgee平台来使用它的上下文编辑功能。查了官方文档，只找到react-i18next和原生i18next的集成方案，于是自己尝试在pages/index.tsx中添加了以下代码，但完全不起作用：

import { withTolgee } from '@tolgee/i18next';
import i18n from 'i18next';
import { UI } from '@tolgee/ui';

withTolgee(i18n, {
    apiUrl: process.env.REACT_APP_TOLGEE_API_URL,
    apiKey: process.env.REACT_APP_TOLGEE_API_KEY,
    ui: UI
}).init({
    supportedLngs: ['en', 'de'],
    fallbackLng: 'en'
});

请问该如何正确在Next.js应用中集成Tolgee与next-i18next？

正确集成步骤 #

1. 确认依赖安装

确保已安装必要的包：

npm install @tolgee/i18next @tolgee/ui next-i18next i18next react-i18next

2. 修改next-i18next配置文件

next-i18next的初始化逻辑需要在专属配置文件中（通常是next-i18next.config.js或.ts）集成Tolgee，而不是在页面文件中单独初始化。以下是完整配置示例：

// next-i18next.config.ts
import type { NextI18NextConfig } from 'next-i18next';
import { withTolgee } from '@tolgee/i18next';
import { UI } from '@tolgee/ui';

const config: NextI18NextConfig = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'de'],
  },
  // 启用Tolgee的关键：包装i18n实例
  use: [
    withTolgee({
      apiUrl: process.env.NEXT_PUBLIC_TOLGEE_API_URL,
      apiKey: process.env.NEXT_PUBLIC_TOLGEE_API_KEY,
      ui: UI,
      // 仅在开发环境启用Tolgee，避免生产环境暴露编辑功能
      enabled: process.env.NODE_ENV === 'development',
    }),
  ],
};

export default config;

3. 调整环境变量命名

Next.js客户端环境变量需要以NEXT_PUBLIC_为前缀，所以把原来的REACT_APP_*改为：

# .env.local
NEXT_PUBLIC_TOLGEE_API_URL="你的Tolgee API地址"
NEXT_PUBLIC_TOLGEE_API_KEY="你的Tolgee项目API密钥"

4. 在_app.tsx中确保正确初始化

确保_app.tsx中使用appWithTranslation包裹根组件，这是next-i18next的标准用法：

// pages/_app.tsx
import { appWithTranslation } from 'next-i18next';
import type { AppProps } from 'next/app';

function MyApp({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

export default appWithTranslation(MyApp);

5. 验证集成效果

启动开发服务器后，访问应用页面，应该能看到Tolgee的浮动编辑按钮，点击即可开启上下文翻译编辑功能。

原代码失效原因 #

直接在index.tsx中初始化i18n会和next-i18next的内置初始化流程冲突——next-i18next会在应用启动时自动初始化i18n实例，单独调用withTolgee(i18n).init()会覆盖或干扰原有配置，导致集成失败。

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