next-translate

You must wrap your next.config.js with the next-translate-plugin.

Standard Webpack Configuration

If you have a simple config:

const nextTranslate = require('next-translate-plugin')
module.exports = nextTranslate()

If you have an existing configuration (e.g., for Webpack), pass your config object to nextTranslate():

const nextTranslate = require('next-translate-plugin')
module.exports = nextTranslate({
  webpack: (config, { isServer, webpack }) => {
    return config;
  }
})

Turbopack Configuration (Next.js 16+)

If you are using Turbopack, you must pass { turbopack: true } as the second argument to avoid startup errors. Otherwise, the plugin will attempt to inject Webpack configurations that Turbopack does not support.

const nextTranslate = require('next-translate-plugin')

// For Next.js 16+ with Turbopack enabled
module.exports = nextTranslate({}, { turbopack: true })

For a more robust detection in Next.js 16+:

const nextTranslate = require('next-translate-plugin')
const isTurbopack = !process.argv.includes('--webpack')

module.exports = nextTranslate(
  {
    // your Next.js config here
  },
  { turbopack: isTurbopack }
)

To upgrade from next-translate@0.x to next-translate@1.0.0, follow these steps to unify your configuration under the webpack loader and remove obsolete build steps or wrappers.

1. Update Dependencies

Update next-translate to ^1.0.0 using your package manager:

yarn add next-translate@^1.0.0
# or
npm install next-translate@^1.0.0

2. Update next.config.js

Replace your manual i18n configuration with the nextTranslate wrapper:

const nextTranslate = require("next-translate");

module.exports = nextTranslate();

3. Clean up i18n configuration

Remove obsolete keys from your i18n.json file, such as currentPagesDir, finalPagesDir, localesPath, and package.

If you were using localesPath to load namespaces from a custom directory, migrate from i18n.json to i18n.js and implement the loadLocaleFrom function:

module.exports = {
  // ...rest of config
  loadLocaleFrom: (lang, ns) =>
    import(`./locales/${lang}/${ns}.json`).then((m) => m.default),
}

4. Remove Build Step artifacts (if applicable)

If you were using the "build step" method:

• Remove next-translate from your package.json scripts (e.g., remove it from dev and build).
• Remove /pages from your .gitignore.
• Rename your pages_ directory to pages.

5. Remove appWithI18n wrapper (if applicable)

If you were using the appWithI18n wrapper in _app.js, remove the import and the wrapper function, exporting your component directly:

import React from 'react'
import type { AppProps } from 'next/app'
// Remove these:
// import appWithI18n from 'next-translate/appWithI18n'
// import i18nConfig from '../i18n'

import '../styles.css'

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

// Change this:
// export default appWithI18n(MyApp, i18nConfig)
// To this:
export default MyApp

6. Update Plural Keys

Replace all _plural suffixes in your translation files with _other to support the new 6-form plural system:

{
  "lorem-ipsum_other": "The value is {{count}}"
}

To enable type-safe translation keys and autocomplete when using useTranslation or getT, you must create a next-translate.d.ts file in your project. This file defines your translation namespaces and maps them to your JSON locale files using the Paths utility from next-translate.

import type { Paths, I18n, Translate } from 'next-translate'

type Tail<T> = T extends [unknown, ...infer Rest] ? Rest : never;

export interface TranslationsKeys {
  // Map your namespace names to the path of your default language JSON files
  common: Paths<typeof import('./locales/en/common.json')>
  home: Paths<typeof import('./locales/en/home.json')>
  // Add all other namespaces here...
}

type TranslationNamespace = keyof TranslationsKeys;

export interface TranslateFunction<Namespace extends TranslationNamespace>  {
  (
    key: TranslationsKeys[Namespace],
    ...rest: Tail<Parameters<Translate>>
  ): string
  <T extends string>(template: TemplateStringsArray): string
};

export interface TypeSafeTranslate<Namespace extends TranslationNamespace>
  extends Omit<I18n, 't'> {
  t: TranslateFunction<Namespace>
}

declare module 'next-translate/useTranslation' {
  export default function useTranslation<
    Namespace extends TranslationNamespace
  >(namespace: Namespace): TypeSafeTranslate<Namespace>
}

declare module 'next-translate/getT' {
  export default function getT<
    Namespace extends TranslationNamespace
  >(locale?: string, namespace: Namespace): Promise<TranslateFunction<Namespace>>  
}