# General Translation React SDKs (gt-react, gt-next, gt-react-native): Quickstart du Pages Router de Next.js URL: https://generaltranslation.com/fr/docs/react/nextjs-pages-router-quickstart.mdx Docs index: https://generaltranslation.com/llms.txt Description: Ajoutez plusieurs langues à une application Next.js avec Pages Router grâce à General Translation en moins de 10 minutes. À la fin de ce guide, votre application Next.js avec Pages Router affichera du contenu en plusieurs langues, avec un sélecteur de langue que vos utilisateurs pourront utiliser. Dans le Pages Router, `gt-next` fonctionne via `getServerSideProps` : à chaque requête, le serveur résout le paramètre régional de l’utilisateur, charge un instantané des traductions et transmet les deux à un [``](/docs/react/reference/components/gt-provider) dans `_app.tsx`, afin que le premier rendu soit déjà traduit. Le point d’entrée `gt-next/server` est réservé à l’App Router et ne fonctionne pas avec le Pages Router. **Prérequis :** * Une application Next.js utilisant le **Pages Router** (Next.js 13.0.0 ou version ultérieure, à l’exclusion de 15.2.1 et 15.2.2) * Node.js 18+ **Remarque :** Si vous utilisez l’App Router, suivez plutôt le [Quickstart Next.js App Router](/docs/react/nextjs-quickstart). Il utilise les Server Components et ne nécessite aucune configuration `getServerSideProps`. ## Quickstart [#quickstart] ### 1. Installez les paquets `gt-next` est la bibliothèque qui gère les traductions dans votre application. `gt` est l’outil CLI qui prépare les traductions pour la production. ```bash npm i gt-next npm i -D gt ``` ```bash yarn add gt-next yarn add --dev gt ``` ```bash bun add gt-next bun add --dev gt ``` ```bash pnpm add gt-next pnpm add --save-dev gt ``` ### 2. Créez un fichier de configuration des traductions Créez un fichier **`gt.config.json`** à la racine de votre projet. Ce fichier indique à la bibliothèque quelles langues vous prenez en charge : ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["en", "es", "fr", "ja"], "files": { "gt": { "output": "public/_gt/[locale].json" } } } ``` * **`defaultLocale`** — la langue dans laquelle votre application est écrite (votre langue source). * **`locales`** — tous les paramètres régionaux disponibles dans votre application. Incluez `defaultLocale`, car le routage internationalisé de Next.js l’exige, puis ajoutez les langues dans lesquelles vous souhaitez traduire votre application. Choisissez-les dans la [liste des paramètres régionaux pris en charge](/docs/platform/dashboard/reference/supported-locales). * **`files.gt.output`** — l’emplacement où la CLI enregistre les fichiers de traduction. `[locale]` est remplacé par chaque code de langue (par ex. `public/_gt/es.json`). Ajoutez `public/_gt/` à votre **`.gitignore`** — ces fichiers sont générés, pas écrits à la main : ```txt title=".gitignore" public/_gt/ ``` ### 3. Configurez le routage internationalisé de Next.js Le Pages Router utilise le [routage internationalisé de Next.js](https://nextjs.org/docs/pages/guides/internationalization) pour les URL préfixées par un paramètre régional et la détection du paramètre régional de la requête. Importez vos paramètres régionaux dans `next.config.ts`, puis encapsulez la configuration avec `withGTConfig`: ```ts title="next.config.ts" import type { NextConfig } from 'next'; import { withGTConfig } from 'gt-next/config'; import gtConfig from './gt.config.json'; const nextConfig: NextConfig = { i18n: { locales: gtConfig.locales, defaultLocale: gtConfig.defaultLocale, }, }; export default withGTConfig(nextConfig); ``` Next.js conserve le paramètre régional par défaut à l’adresse `/` et ajoute un préfixe aux autres paramètres régionaux, tels que `/es` et `/fr`. Vous n’avez besoin ni du middleware `gt-next` ni d’un segment de route `pages/[locale]`. Consultez [le routage des paramètres régionaux avec le Pages Router](/docs/react/nextjs/pages-router-middleware) pour en savoir plus sur la détection et la migration. ### 4. Ajouter une fonction de chargement pour les traductions locales Créez un fichier **[`loadTranslations`](/docs/react/reference/functions/load-translations)** à la racine du projet (ou dans le répertoire `src/`). Cela indique à `gt-next` comment charger les fichiers de traduction générés par la CLI : ```ts title="loadTranslations.ts" export default async function loadTranslations(locale: string) { try { const translations = await import(`./public/_gt/${locale}.json`); return translations.default; } catch { return {}; } } ``` **Remarque :** Ces fichiers de traduction n’existent pas tant que vous ne les avez pas créés avec [`npx gt generate`](/docs/cli/reference/commands/generate) (aucune clé API requise) ou [`npx gt translate`](/docs/cli/reference/commands/translate) (avec des identifiants). D’ici là, le bundler affiche un avertissement indiquant que le répertoire `public/_gt` est introuvable, et le `try`/`catch` ci-dessus renvoie `{}` afin que l’application continue de fonctionner avec du contenu non traduit. `withGTConfig` détecte automatiquement un fichier `loadTranslations.[js|ts]` à la racine de votre projet ou dans le répertoire `src/` — aucune configuration supplémentaire n’est requise. **Remarque :** Les traductions locales sont intégrées à votre application ; elles se chargent donc instantanément, sans dépendre de services externes. Consultez [Stocker les traductions](/docs/react/guides/storing-translations) pour en savoir plus sur les détails et les compromis associés. ### 5. Encapsulez getServerSideProps dans vos pages Encapsulez le `getServerSideProps` de chaque page avec **`withGTServerSideProps`**. À chaque requête, il lit le paramètre régional que Next.js a résolu dans `context.locale`, charge un instantané de traductions pour ce paramètre régional et injecte les deux dans les props de votre page : ```tsx title="pages/index.tsx" import type { GetServerSideProps } from 'next'; import { withGTServerSideProps } from 'gt-next'; export const getServerSideProps: GetServerSideProps = withGTServerSideProps( async (context) => { return { props: { // vos propres props }, }; } ); ``` Si une page n’a pas besoin de ses propres props côté serveur, appelez-la sans argument : ```tsx title="pages/about.tsx" import { withGTServerSideProps } from 'gt-next'; export const getServerSideProps = withGTServerSideProps(); ``` `withGTServerSideProps` ajoute `locale` et `translations` à vos props (ainsi qu’un indicateur interne `enableI18n`). Si votre fonction interne renvoie `redirect` ou `notFound`, le résultat est transmis tel quel, sans charger les traductions. ### 6. Ajoutez GTProvider à votre application Le composant **[`GTProvider`](/docs/react/reference/components/gt-provider)** donne à toute votre application accès aux traductions. Dans `_app.tsx`, récupérez les props injectées depuis `pageProps` et transmettez-les au provider. Le type **`WithGTServerSideProps`** décrit cette structure injectée : ```tsx title="pages/_app.tsx" import type { AppProps } from 'next/app'; import Router from 'next/router'; import { GTProvider, type WithGTServerSideProps } from 'gt-next'; export default function App({ Component, pageProps, }: AppProps) { const { locale, translations } = pageProps; return ( { void Router.push(Router.pathname, Router.asPath, { locale: nextLocale, }); }} > ); } ``` Comme le paramètre régional et les traductions arrivent avec la réponse du serveur, le contenu s’affiche dès le premier rendu dans la langue de l’utilisateur — aucun état de chargement côté client. Le callback `_reload` transmet les changements de paramètre régional au routeur Next.js afin qu’il charge les props de page du paramètre régional sélectionné. ### 7. Marquer le contenu à traduire Maintenant, encapsulez le texte que vous voulez traduire avec le composant **[``](/docs/react/reference/components/t)**. [``](/docs/react/reference/components/t) signifie "translate" : ```tsx title="pages/index.tsx" import { T } from 'gt-next'; export default function Home() { return (

Welcome to my app

This content will be translated automatically.
); } ``` Vous pouvez encapsuler autant ou aussi peu de JSX que vous le souhaitez dans [``](/docs/react/reference/components/t). Tout ce qu’il contient — le texte, les éléments imbriqués, même la mise en forme — est traduit comme une seule unité. ### 8. Ajouter un sélecteur de langue Ajoutez un **[``](/docs/react/reference/components/locale-selector)** pour que les utilisateurs puissent changer de langue : ```tsx title="pages/index.tsx" import { T, LocaleSelector } from 'gt-next'; export default function Home() { return (

Welcome to my app

This content will be translated automatically.
); } ``` [`LocaleSelector`](/docs/react/reference/components/locale-selector) affiche un menu déroulant contenant les langues de votre `gt.config.json`. Lorsque l'utilisateur choisit une langue, le callback dans `_app.tsx` redirige vers l'URL localisée et Next.js enregistre ce choix dans le cookie `NEXT_LOCALE`. Le serveur affiche ensuite le paramètre régional sélectionné. ### 9. Configurer les variables d’environnement (facultatif) Pour voir les traductions pendant le développement, vous avez besoin de clés API de General Translation. Elles activent la **traduction à la demande** : votre application traduit le contenu en temps réel au fur et à mesure du développement. Créez un fichier **`.env.local`** : ```bash title=".env.local" GT_API_KEY="your-api-key" GT_PROJECT_ID="your-project-id" ``` Obtenez gratuitement vos clés sur [dash.generaltranslation.com](https://dash.generaltranslation.com/en-US/signin) ou en exécutant : ```bash npx gt auth ``` **Avertissement :** Pour le développement, utilisez une clé commençant par `gtx-dev-`. Les clés de production (`gtx-api-`) sont réservées au CI/CD. N’exposez jamais `GT_API_KEY` dans le navigateur et ne l’ajoutez jamais au contrôle de version. ### 10. Vérifiez que tout fonctionne Démarrez votre serveur de développement : ```bash npm run dev ``` ```bash yarn dev ``` ```bash bun dev ``` ```bash pnpm dev ``` Ouvrez [http://localhost:3000](http://localhost:3000) et utilisez le menu déroulant des langues pour changer de langue. Vous devriez voir votre contenu traduit. **Remarque :** En développement, les traductions se font à la demande. Il est donc possible qu’un bref état de chargement apparaisse la première fois que vous passez à une nouvelle langue. En production, les traductions sont pré-générées et se chargent instantanément. ### 11. Traduire des chaînes (pas seulement du JSX) Pour les chaînes simples — comme les attributs `placeholder`, les valeurs `aria-label` ou le texte `alt` — utilisez le hook **[`useGT`](/docs/react/reference/hooks/use-gt)** : ```tsx title="pages/contact.tsx" import { useGT } from 'gt-next'; export default function ContactPage() { const gt = useGT(); return (
); } ``` ### 12. Déployer en production En production, les traductions sont pré-générées au build (aucun appel d’API en temps réel). Ajoutez la commande translate à votre script de build : ```json title="package.json" { "scripts": { "build": "npx gt translate && next build" } } ``` Définissez vos variables d’environnement de **production** dans votre fournisseur d’hébergement (Vercel, Netlify, etc.) : ```bash GT_PROJECT_ID=your-project-id GT_API_KEY=gtx-api-your-production-key ``` **Avertissement :** Les clés de production commencent par `gtx-api-` (et non `gtx-dev-`). Récupérez-en une sur [dash.generaltranslation.com](https://dash.generaltranslation.com). Ne la préfixez jamais avec `NEXT_PUBLIC_`. C'est tout — votre application est désormais multilingue. 🎉 ## Dépannage [#troubleshooting] Oui — [``](/docs/react/reference/components/gt-provider) nécessite les props `locale` et `translations`, et elles n'existent que sur les pages dont `getServerSideProps` est encapsulé. Pour les pages qui ne récupèrent pas leurs propres données, exportez la version sans argument : ```tsx export const getServerSideProps = withGTServerSideProps(); ``` Oui. Encapsulez la page avec `withGTStaticProps` et continuez à passer les props générées à [`GTProvider`](/docs/react/reference/components/gt-provider) dans `_app.tsx`. Consultez le [guide de génération de site statique du Pages Router](/docs/react/nextjs/pages-router-static-site-generation) pour la configuration complète. Vérifiez que `_reload` appelle `Router.push` avec l'option `locale` sélectionnée, comme indiqué ci-dessus. Après une sélection, l'URL doit utiliser le préfixe du paramètre régional et le cookie `NEXT_LOCALE` doit contenir ce paramètre régional. C'est normal. En développement, les traductions se font à la demande (votre contenu est traduit en temps réel via l'API). Ce délai **n'existe pas en production** — toutes les traductions sont pré-générées par [`npx gt translate`](/docs/cli/reference/commands/translate). ## Next steps - /docs/react/guides/translating-jsx - /docs/react/guides/translating-strings - /docs/react/guides/managing-locales - /docs/react/guides/formatting-variables ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.