# General Translation Knowledge Base: Comment migrer de next-intl vers gt-next ?
URL: https://generaltranslation.com/fr/kb/migrate-from-next-intl.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Remplacez le plugin, le middleware et le fournisseur de next-intl par ceux de gt-next, reprenez son réglage de préfixe du paramètre régional et chargez messages/en.json comme dictionnaire gt-next pour que vos messages ICU et vos traductions existants continuent de fonctionner. Mappez les chemins localisés avant de supprimer le routage de next-intl, puis intégrez progressivement le texte dans `<T>`, une route à la fois.
Category: Internationalisation
Last updated: 2026-11-11
Authors: Kevin Wu
Published: 2026-11-11

next-intl et gt-next localisent tous deux les applications Next.js App Router avec des routes préfixées par le paramètre régional et des Composants Serveur : la structure de l&#39;application ne change donc presque pas. Vos messages next-intl sont déjà au format ICU MessageFormat, celui-là même qu&#39;utilisent les dictionnaires gt-next. Vous pouvez donc conserver `messages/en.json` et vos catalogues traduits le temps de changer de bibliothèque, puis intégrer le texte directement dans [`<T>`](/docs/react/reference/components/t) à votre rythme.

Si vos catalogues fonctionnent et que seule la production des traductions est lente, une migration n&#39;est peut-être pas nécessaire. Si vous conservez next-intl, la CLI `gt` traduit ses catalogues sur place. (Voir [next-intl vs. gt-next](/kb/next-intl-vs-gt-next).)

## Quelles sont les correspondances entre les API de next-intl et celles de gt-next ?

| next-intl                                                                          | gt-next                                                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defineRouting({ locales, defaultLocale })`                                        | `defaultLocale` et `locales` dans `gt.config.json`                                                                                                                                                                                                                                  |
| `createNextIntlPlugin()` dans `next.config.ts`                                     | [`withGTConfig`](/docs/react/nextjs/config) depuis `gt-next/config`                                                                                                                                                                                                                 |
| `createMiddleware(routing)` dans `proxy.ts`                                        | [`createNextMiddleware`](/docs/react/nextjs/reference/functions/create-next-middleware) depuis `gt-next/middleware`                                                                                                                                                                 |
| `localePrefix: 'as-needed'` / `'always'`                                           | `prefixDefaultLocale: false` (valeur par défaut) / `true`                                                                                                                                                                                                                           |
| `getRequestConfig` dans `i18n/request.ts`                                          | Un fichier `getLocale.ts` à la racine qui lit `next/root-params`, ainsi que l&#39;option `dictionary`                                                                                                                                                                               |
| `NextIntlClientProvider`                                                           | [`GTProvider`](/docs/react/reference/components/gt-provider) dans `app/[locale]/layout.tsx`                                                                                                                                                                                         |
| `useTranslations('ns')`                                                            | [`useTranslations`](/docs/react/reference/hooks/use-translations)`('ns')` depuis `gt-next`                                                                                                                                                                                          |
| `await getTranslations('ns')`                                                      | `await` [`getTranslations`](/docs/react/nextjs/reference/functions/get-translations)`('ns')` depuis `gt-next/server`                                                                                                                                                                |
| `t.rich` et `t.markup`                                                             | [`<T>`](/docs/react/reference/components/t) encapsulant directement le JSX                                                                                                                                                                                                          |
| `useFormatter` / `getFormatter`                                                    | [`<Num>`](/docs/react/reference/components/num), [`<Currency>`](/docs/react/reference/components/currency), [`<DateTime>`](/docs/react/reference/components/datetime) et [`<RelativeTime>`](/docs/react/reference/components/relative-time), ou des arguments ICU dans les messages |
| [`useLocale` / `getLocale`](https://next-intl.dev/docs/usage/configuration#locale) | [`useLocale`](/docs/react/reference/hooks/use-locale) / [`getLocale`](/docs/react/nextjs/reference/functions/get-locale)                                                                                                                                                            |
| `setRequestLocale(locale)`                                                         | Inutile pour les pages et les mises en page avec `getLocale.ts` ; [`registerLocale`](/docs/react/nextjs/reference/functions/register-locale) pour les gestionnaires de routes et les routes d&#39;images                                                                                  |
| `Link` depuis `createNavigation`                                                   | [`Link`](/docs/react/nextjs/link) depuis `gt-next/link`                                                                                                                                                                                                                             |
| `useRouter` / `getPathname` / `redirect`                                           | Les API natives de Next.js, combinées à [`useLocalizeHref`](/docs/react/nextjs/reference/hooks/use-localize-href) ou [`getLocalizeHref`](/docs/react/nextjs/reference/functions/get-localize-href)                                                                                  |
| Cookie `NEXT_LOCALE`                                                               | `generaltranslation.locale`, renommable via `headersAndCookies.localeCookieName`                                                                                                                                                                                                    |

## Étape 1 : remplacer le plugin et conserver vos messages

Installez `gt-next` et la CLI `gt`, puis indiquez vos langues dans `gt.config.json`. Faites pointer `withGTConfig` vers votre catalogue source existant et reprenez la structure d&#39;URL de next-intl :

```ts title="next.config.ts"
import type { NextConfig } from 'next';
import { withGTConfig } from 'gt-next/config';

const nextConfig: NextConfig = {};

export default withGTConfig(nextConfig, {
  dictionary: './messages/en.json',
  prefixDefaultLocale: true, // valeur par défaut de next-intl : localePrefix: 'always'
  headersAndCookies: { localeCookieName: 'NEXT_LOCALE' }, // conserve la langue des visiteurs qui reviennent
});
```

Omettez `prefixDefaultLocale` si vous utilisiez `localePrefix: 'as-needed'`. Définissez les options de routage dans `withGTConfig`, et pas uniquement dans le middleware, car le composant `<Link>` de gt-next les lit à cet endroit.

Cet exemple couvre les préfixes de paramètre régional standard, comme `/de/about`. Si votre appel à `defineRouting` personnalise les routes, reportez chacune de ces personnalisations avant que l&#39;étape 2 ne le supprime :

* **Chemins localisés** (`pathnames`, comme `/de/ueber-uns`) : associez chacun d&#39;eux à l&#39;aide de l&#39;option [`pathConfig`](/docs/react/nextjs/reference/functions/create-next-middleware#path-config) de gt-next, qui utilise la même structure : un chemin partagé et un chemin localisé par paramètre régional.
* **Préfixes personnalisés, routage par domaine ou `localePrefix: 'never'` :** gt-next n&#39;a pas d&#39;équivalent direct. Définissez les nouvelles URL et ajoutez des redirections permanentes depuis les anciennes avant de supprimer le routage de next-intl.

Pour continuer à servir vos traductions relues, ajoutez un fichier `loadDictionary.ts` à la racine du projet. gt-next le détecte automatiquement :

```ts title="loadDictionary.ts"
export default async function loadDictionary(locale: string) {
  try {
    return (await import(`./messages/${locale}.json`)).default;
  } catch {
    return {}; // un nouveau paramètre régional sans catalogue utilise les traductions de General Translation
  }
}
```

Les entrées de ces fichiers sont prioritaires. La traduction de General Translation est affichée pour toute clé absente d&#39;un catalogue. Si `gt.config.json` répertorie déjà ces catalogues sous `files`, supprimez cette entrée : gt-next les charge désormais comme dictionnaires, et chaque chaîne de caractères ne doit avoir qu&#39;une seule source de traduction.

## Étape 2 : remplacer le middleware, la mise en page et la configuration des requêtes

Remplacez le middleware de next-intl dans `proxy.ts` (`middleware.ts` sur Next.js 15 et versions antérieures) :

```ts title="proxy.ts"
import { createNextMiddleware } from 'gt-next/middleware';

export default createNextMiddleware();

export const config = {
  matcher: ['/((?!api|static|.*\\..*|_next).*)'],
};
```

Une fois ses routes mappées, supprimez `i18n/request.ts` et `i18n/routing.ts`. Ajoutez à la place un fichier `getLocale.ts` à la racine, afin que les pages et les mises en page puissent s&#39;afficher de manière statique sans `setRequestLocale` :

```ts title="getLocale.ts"
import { locale } from 'next/root-params';

export default async function getLocale() {
  return await locale();
}
```

`next/root-params` nécessite Next.js 15.5 ou une version ultérieure ; pour les versions 15.2 à 15.4, consultez le [guide du middleware](/docs/react/nextjs/app-router-middleware#root-locale). Remplacez ensuite le fournisseur dans la mise en page de votre paramètre régional :

```tsx title="app/[locale]/layout.tsx"
import { GTProvider, getLocales } from 'gt-next';
import { getLocale } from 'gt-next/server';

export function generateStaticParams() {
  return getLocales().map((locale) => ({ locale }));
}

export default async function LocaleLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang={await getLocale()}>
      <body>
        <GTProvider>{children}</GTProvider>
      </body>
    </html>
  );
}
```

Par défaut, gt-next se rabat sur `defaultLocale` lorsque le segment de paramètre régional n&#39;est pas pris en charge. Pour renvoyer une erreur 404, comme le fait la vérification `hasLocale` de next-intl, vérifiez le segment avec [`isLocaleSupported`](/docs/react/nextjs/reference/functions/is-locale-supported), puis appelez `notFound()`.

## Étape 3 : Modifier les importations

Une fois le catalogue chargé en tant que dictionnaire, seule la ligne d&#39;importation change pour la plupart des composants :

```tsx
// Avant
import { useTranslations } from 'next-intl';
import { getTranslations } from 'next-intl/server';
import { Link } from '@/i18n/navigation';

// Après
import { useTranslations } from 'gt-next';
import { getTranslations } from 'gt-next/server';
import Link from 'gt-next/link';
```

`t('heading')`, les espaces de noms, les espaces réservés `{name}` et les messages ICU `plural` et `select` fonctionnent tels quels, y compris dans `generateMetadata`. Trois approches doivent être modifiées :

* **`t.rich` et `t.markup`.** La fonction [`t()`](/docs/react/reference/hooks/use-translations) de gt-next renvoie une chaîne de caractères. Intégrez directement le texte enrichi dans [`<T>`](/docs/react/reference/components/t), avec de vrais éléments.
* **`t.raw` avec des tableaux.** gt-next ne propose pas `t.raw` et interprète un tableau de dictionnaire uniquement comme un message accompagné de ses options. Restructurez les listes sous forme d&#39;objets imbriqués et lisez-les avec [`t.obj()`](/docs/react/guides/translating-with-dictionaries#objects) ou clé par clé.
* **Clés manquantes.** next-intl journalise une erreur et affiche un contenu de secours ; gt-next lève une exception. Recherchez donc les occurrences d&#39;une clé avant de la supprimer du catalogue.

Exécutez ensuite [`npx gt validate`](/docs/cli/reference/commands/validate) pour repérer les entrées dont la syntaxe ICU n&#39;est pas valide, puis [`npx gt translate --dictionary ./messages/en.json`](/docs/cli/reference/commands/translate) pour générer les traductions des clés absentes de vos catalogues et de tout nouveau paramètre régional. La CLI ne détecte automatiquement un dictionnaire que s&#39;il s&#39;appelle `dictionary.json`, `.ts` ou `.js` et se trouve à la racine du projet ou dans `src/`. Passez donc `--dictionary ./messages/en.json` aux deux commandes, en local comme en CI, tant que vous conservez le catalogue :

```bash
npx gt validate --dictionary ./messages/en.json
npx gt translate --dictionary ./messages/en.json
```

## Étape 4 : Intégrer le texte dans le code, une route à la fois

Les clés continuent de fonctionner : vous pouvez donc vous arrêter ici. Pour garder le texte à côté du JSX qui l&#39;affiche, déplacez-le dans [`<T>`](/docs/react/reference/components/t), route par route, en commençant par les messages `t.rich` :

```tsx
// Avant : "terms": "By continuing you accept the <link>terms</link>."
t.rich('terms', { link: (chunks) => <a href="/terms">{chunks}</a> });

// Après
<T>
  By continuing you accept the <a href="/terms">terms</a>.
</T>
```

Dans les Composants Serveur asynchrones, utilisez [`getGT`](/docs/react/nextjs/reference/functions/get-gt) pour les simples chaînes de caractères. La même commande [`npx gt translate`](/docs/cli/reference/commands/translate) génère de nouvelles traductions pour le texte que vous intégrez directement dans le code, en s&#39;appuyant sur le JSX environnant comme contexte. Les relecteurs peuvent les corriger dans le [tableau de bord](/docs/platform/dashboard/guides/reviewing-translations), et le glossaire d&#39;un [groupe de contexte](/docs/platform/dashboard/guides/defining-context-for-translations) assure la cohérence de votre terminologie. Supprimez chaque clé de vos catalogues dès qu&#39;elle n&#39;est plus utilisée nulle part.

## Étape 5 : Supprimer next-intl

Lorsqu&#39;une recherche de `next-intl` ne renvoie plus aucun résultat, supprimez la dépendance ainsi que `createNextIntlPlugin`, puis testez une compilation de production dans chaque paramètre régional. Ajoutez ensuite [`npx gt translate`](/docs/cli/reference/commands/translate) à votre processus de compilation ou à votre [CI](/kb/translations-in-ci) pour que les nouveaux textes soient livrés déjà traduits, en ajoutant `--dictionary ./messages/en.json` si vous avez conservé le catalogue.

## Questions fréquentes

### Mes URL vont-elles changer ?

Pas pour les préfixes de paramètre régional standard, à condition de reprendre le réglage de next-intl : `localePrefix: 'as-needed'` correspond au comportement par défaut de gt-next, et `'always'` à `prefixDefaultLocale: true`. gt-next utilise également un segment `app/[locale]`. Les chemins localisés nécessitent une correspondance `pathConfig` explicite. Quant aux préfixes personnalisés et au routage par domaine, ils n&#39;ont pas d&#39;équivalent direct dans gt-next : mettez donc en place des redirections pour ces URL et testez chaque route avant de supprimer le routage de next-intl.

### Vais-je perdre mes traductions existantes ?

Non. Chargez vos catalogues next-intl avec [`loadDictionary`](/docs/react/reference/functions/load-dictionary) : ils s&#39;affichent comme avant. General Translation ne traduit que les clés manquantes dans ces catalogues, ainsi que tout contenu que vous déplacez ensuite en intégré dans [`<T>`](/docs/react/reference/components/t).

### gt-next prend-il en charge le rendu statique ?

Oui. Ajoutez un fichier `getLocale.ts` à la racine, ainsi que `generateStaticParams`. (Voir [génération de sites statiques](/docs/react/nextjs/app-router-static-site-generation).)

### gt-next est-il gratuit ?

gt-next est distribué sous licence MIT et affiche les traductions incluses dans le bundle sans nécessiter de compte. La génération de traductions avec General Translation est [facturée à l&#39;usage](https://generaltranslation.com/pricing).

## Points clés

* Remplacez le plugin, le middleware, la configuration de requête et le fournisseur de next-intl par `withGTConfig`, [`createNextMiddleware`](/docs/react/nextjs/reference/functions/create-next-middleware), `getLocale.ts` et [`GTProvider`](/docs/react/reference/components/gt-provider).
* Conservez `messages/en.json` comme dictionnaire gt-next, et vos catalogues traduits via [`loadDictionary`](/docs/react/reference/functions/load-dictionary) ; les messages ICU fonctionnent tels quels.
* Alignez `localePrefix` sur `prefixDefaultLocale` et conservez le cookie `NEXT_LOCALE` pour que les URL standard par paramètre régional et les préférences enregistrées restent valides ; mappez les chemins localisés avec `pathConfig` avant de supprimer le routage de next-intl.
* Réécrivez `t.rich` avec [`<T>`](/docs/react/reference/components/t), puis intégrez le reste du contenu directement dans le code, route par route.

## Related questions

- [Alternatives à next-intl : gt-next ou next-intl](https://generaltranslation.com/fr/kb/next-intl-vs-gt-next.mdx): next-intl rend les traductions que vous fournissez dans un catalogue de messages pour chaque langue. gt-next rend lui aussi des traductions, mais General Translation les génère en plus à partir du texte intégré directement dans votre JSX. Les deux sont sous licence MIT et prennent en charge l’App Router et les Composants serveur. Si vos catalogues next-intl fonctionnent déjà, vous pouvez les conserver et confier leur traduction à General Translation, sans migration.
- [Comment ajouter l’i18n à une application Next.js App Router ?](https://generaltranslation.com/fr/kb/add-i18n-to-nextjs.mdx): Commencez par gt init pour configurer General Translation dans un projet App Router pris en charge, puis balisez le contenu source, générez les traductions et vérifiez le changement de langue. gt-next conserve les textes dans le JSX avec leur contexte de traduction ; la CLI, l’éditeur du tableau de bord et Locadex prennent en charge la génération, la relecture et les mises à jour continues. Ce guide présente également la configuration initiale explicite avec des fichiers locaux.
- [Comment configurer le SEO d’une application Next.js multilingue ?](https://generaltranslation.com/fr/kb/multilingual-nextjs-seo.mdx): Attribuez à chaque langue sa propre URL préfixée, comme /en/about et /es/about, puis publiez html lang, une URL canonique autoréférente, des variantes localisées hreflang avec x-default, un titre et une description traduits, ainsi qu’une entrée de plan de site pour chaque langue publiée. Marquez les versions non publiées en noindex. Le package gt-next de General Translation associe chaque langue à sa propre URL et traduit les titres avec getGT.
- [Redirections linguistiques et SEO : URL, cookie ou Accept-Language ?](https://generaltranslation.com/fr/kb/locale-routing-seo.mdx): Laissez l’URL déterminer la langue de chaque page que vous souhaitez faire indexer, car Googlebot n’envoie aucun en-tête Accept-Language et explore principalement depuis des adresses américaines. Ne vous servez du choix enregistré dans un cookie, puis d’Accept-Language, que pour décider vers où redirige une racine neutre comme /, avec une redirection temporaire 302 ou 307.
- [Comment maintenir les traductions à jour à chaque déploiement ?](https://generaltranslation.com/fr/kb/translations-in-ci.mdx): Exécutez la traduction comme une étape du pipeline avant chaque compilation de production, afin que les nouveaux textes soient livrés traduits avec le déploiement qui les ajoute. Le CLI gt de General Translation s’en charge avec npx gt translate, à l’aide d’une clé API de projet et d’un identifiant de projet stockés comme secrets CI.

## Previous and next questions

- Previous question: [Quels outils de traduction facturent à l’usage plutôt qu’au nombre de licences utilisateur ?](https://generaltranslation.com/fr/kb/translation-pricing-without-seat-fees.mdx)
- Next question: [Comment migrer de react-i18next vers gt-react ?](https://generaltranslation.com/fr/kb/migrate-from-react-i18next.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/fr/kb/sitemap.md) for every article.