# gt-next: General Translation Next.js SDK: Démarrage rapide du Pages Router URL: https://generaltranslation.com/fr/docs/next/tutorials/quickstart-pages-router.mdx --- title: Démarrage rapide du Pages Router description: Ajoutez plusieurs langues à votre application Next.js Pages Router en moins de 10 minutes --- À la fin de ce guide, votre application Next.js 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 détermine le paramètre régional de l’utilisateur, charge un instantané des traductions et transmet les deux à un `` dans `_app.tsx`, afin que le premier rendu soit déjà traduit. **Prérequis :** * Une application Next.js utilisant le **Pages Router** * Node.js 18+ **Vous utilisez l’App Router ?** Suivez plutôt le [démarrage rapide Next.js](/docs/next) — il utilise des composants serveur et ne nécessite aucune configuration de `getServerSideProps`. *** ## Étape 1 : Installez les packages `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 ``` *** ## Étape 2 : Configurez votre config Next.js `gt-next` utilise un plugin Next.js appelé **`withGTConfig`** pour configurer l’internationalisation au build. Enveloppez votre config Next.js existante avec ce plugin : ```ts title="next.config.ts" import { withGTConfig } from 'gt-next/config'; const nextConfig = {}; export default withGTConfig(nextConfig); ``` Ce plugin lit vos paramètres de traduction et fait le lien entre tous les éléments en coulisses. La configuration est identique pour l’App Router et le Pages Router — aucune option spécifique au routeur n’est nécessaire. *** ## Étape 3 : Créer un fichier de configuration des traductions Créez un fichier **`gt.config.json`** à la racine de votre projet. Il indique à la bibliothèque les langues prises en charge : ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr", "ja"], "files": { "gt": { "output": "public/_gt/[locale].json" } } } ``` * **`defaultLocale`** — la langue dans laquelle votre application est écrite (votre langue source). * **`locales`** — les langues vers lesquelles vous souhaitez traduire. Choisissez-en une dans la [liste des langues prises en charge](/docs/platform/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/ ``` *** ## Étape 4 : Ajoutez une fonction de chargement pour les traductions locales Créez un fichier **`loadTranslations`** à la racine de votre 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 {}; } } ``` `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 nécessaire. **Pourquoi les traductions locales ?** Les traductions locales sont embarquées avec votre application, elles se chargent donc instantanément sans dépendre de services externes. Consultez le [guide sur le stockage local des traductions](/docs/next/guides/local-tx) pour en savoir plus sur les détails et les compromis associés. *** ## Étape 5 : Enveloppez `getServerSideProps` dans vos pages Enveloppez le `getServerSideProps` de chaque page avec **`withGTServerSideProps`**. À chaque requête, il détermine le paramètre régional de l'utilisateur — à partir du cookie `generaltranslation.locale` s'il est défini, sinon à partir de l'en-tête `Accept-Language` —, charge un instantané des traductions pour ce paramètre régional et les injecte tous 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 chargement des traductions. *** ## Étape 6 : Ajouter GTProvider à votre application Le composant **`GTProvider`** permet à toute votre application d’accéder aux traductions. Dans `_app.tsx`, récupérez les props injectées depuis `pageProps` et transmettez-les au provider. Le type **`WithGTServerSideProps`** décrit la structure injectée : ```tsx title="pages/_app.tsx" import type { AppProps } from 'next/app'; import { GTProvider, WithGTServerSideProps } from 'gt-next'; export default function App({ Component, pageProps, }: AppProps) { const { locale, translations, ...restPageProps } = pageProps; return ( ); } ``` Puisque le paramètre régional et les traductions sont renvoyés avec la réponse du serveur, le premier rendu s’effectue déjà dans la langue de l’utilisateur — sans état de chargement côté client. *** ## Étape 7 : Marquer le contenu à traduire À présent, entourez du composant **``** tout texte que vous souhaitez traduire. `` 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 placer autant ou aussi peu de JSX que vous le souhaitez dans ``. Tout ce qu’il contient — texte, éléments imbriqués, même la mise en forme — est traduit comme une seule unité. *** ## Étape 8 : Ajouter un sélecteur de langue Ajoutez simplement un **``** 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` affiche un menu déroulant contenant les langues de votre `gt.config.json`. Lorsque l’utilisateur choisit une langue, `gt-next` enregistre ce choix dans le cookie `generaltranslation.locale`, puis recharge la page afin que le serveur réaffiche l’ensemble dans le nouveau paramètre régional. *** ## Étape 9 : Configurer les variables d’environnement (facultatif) Pour afficher les traductions en 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 pendant le 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/signup) ou en exécutant : ```bash npx gt auth ``` 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. *** ## Étape 10 : Vérifiez que cela 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 de langue pour changer de langue. Vous devriez voir votre contenu traduit. En développement, les traductions sont générées à la demande : il est possible qu’un bref état de chargement s’affiche 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. *** ## Étape 11 : Traduire les chaînes (pas seulement le JSX) Pour les chaînes simples — comme les attributs `placeholder`, les valeurs `aria-label` ou le texte `alt` — utilisez le hook **`useGT`** : ```tsx title="pages/contact.tsx" import { useGT } from 'gt-next'; export default function ContactPage() { const gt = useGT(); return (
); } ``` *** ## Étape 12 : Déployer en production En production, les traductions sont pré-générées au build (sans appels 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** auprès de votre hébergeur (Vercel, Netlify, etc.) : ```bash GT_PROJECT_ID=your-project-id GT_API_KEY=gtx-api-your-production-key ``` 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 Oui — `` nécessite les props `locale` et `translations`, et elles n'existent que sur les pages dont le `getServerSideProps` est enveloppé. Pour les pages qui ne récupèrent pas leurs propres données, exportez la version sans argument : ```tsx export const getServerSideProps = withGTServerSideProps(); ``` Non. La résolution du paramètre régional nécessite des données propres à chaque requête (le cookie de paramètre régional et l'en-tête `Accept-Language`), qui ne sont pas disponibles lors de la génération statique. `gt-next` ne fournit pas de helper `getStaticProps` pour le Pages Router. `gt-next` stocke la préférence linguistique de l'utilisateur dans un cookie appelé `generaltranslation.locale`. Si vous avez déjà fait des tests avec une autre langue, ce cookie peut remplacer votre sélection. Supprimez vos cookies, puis réessayez. * [Chrome](https://support.google.com/chrome/answer/95647) * [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored) * [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0) 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`. *** ## Étapes suivantes * [**Guide du composant ``**](/docs/next/guides/t) — Découvrez les variables, les pluriels et les schémas de traduction avancés * [**Guide de traduction de chaînes**](/docs/next/guides/strings) — Découvrez `useGT` en profondeur * [**Composants variables**](/docs/next/guides/variables) — Gérez le contenu dynamique avec ``, ``, `` et `` * [**Pluralisation**](/docs/next/api/components/plural) — Gérez les formes plurielles avec le composant `` * [**Déploiement en production**](/docs/next/tutorials/quickdeploy) — Configuration CI/CD, mise en cache et optimisation des performances * [**Chaînes partagées**](/docs/next/guides/shared-strings) — Traduisez du texte dans des tableaux, des objets de configuration et des données partagées avec `msg()`