Démarrage rapide avec Next.js

Aperçu

Ce guide de démarrage rapide vous expliquera comment configurer votre application Next.js avec gt-next.

À la fin de ce guide, vous disposerez d'une application Next.js prête à commencer la traduction de contenu.

Dans ce guide, nous aborderons les points suivants :

Installation

Configuration

Utilisation

Tester votre application

Déploiement

Prérequis

Une application Next.js utilisant l'App Router
Connaissances de base de Next.js et JavaScript

Installation

Installez les packages gt-next et gtx-cli :

npm i gt-next
npm i --save-dev gtx-cli

yarn add gt-next
yarn add --dev gtx-cli

bun add gt-next
bun add --dev gtx-cli

pnpm add gt-next
pnpm add --save-dev gtx-cli

Configuration automatique : Nous avons un assistant de configuration expérimental qui peut vous aider à configurer votre projet avec gt-next.

Essayez-le en exécutant npx gtx-cli@latest. Vous devrez toujours internationaliser manuellement les chaînes de caractères, mais cela vous aidera à commencer.

Consultez le guide de référence de l'Assistant de configuration pour plus d'informations.

Alternativement, si vous souhaitez que votre outil d'IA comme Claude Code, Cursor, ou Windsurf configure automatiquement votre projet, vous pouvez utiliser notre serveur mcp.

Configuration

`withGTConfig`

La fonction withGTConfig est une fonction utilisée pour initialiser le SDK dans une application Next.js.

Placez ceci dans votre fichier next.config.[js|ts].

next.config.ts

import { withGTConfig } from 'gt-next/config';

const nextConfig = {
  // Your next.config.ts options
};

export default withGTConfig(nextConfig, {
  // Additional GT configuration options
});

Consultez la référence API de withGTConfig pour plus d'informations.

`GTProvider`

gt-next exporte également un composant GTProvider. Ce composant est utilisé pour fournir un contexte aux composants côté client dans votre application Next.js.

Le GTProvider et withGTConfig fonctionnent ensemble pour fournir un contexte à votre application.

Ce contexte inclut :

La gestion de la langue actuelle de l'utilisateur
Les traductions pertinentes pour cette langue
Le contexte pour le hook useGT
Le contexte pour le hook useDict

Tout d'abord, ajoutez le composant GTProvider à la racine du layout de votre application. Il doit être placé aussi haut que possible dans votre arbre de composants.

src/layout.tsx

import { GTProvider } from 'gt-next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}

Si vous avez plusieurs layouts racines, placez le GTProvider dans chacun d'eux.

Ensuite, créez un fichier gt.config.json à la racine de votre projet. Ce fichier est utilisé pour configurer à la fois l'outil gtx-cli et la bibliothèque gt-next.

gt.config.json

{
  "defaultLocale": "en",
  "locales": ["fr", "es"]
}

Vous devez personnaliser les champs defaultLocale et locales pour correspondre à votre projet. Consultez la liste des langues prises en charge pour plus d'informations.

withGTConfig détectera automatiquement le fichier gt.config.json dans votre projet et l'utilisera pour configurer le SDK.

Variables d'environnement

Définissez les variables d'environnement suivantes :

GT_API_KEY="" # Votre clé API General Translation Developer
GT_PROJECT_ID="" # L'identifiant de votre projet General Translation

Assurez-vous que votre variable de clé API n'est définie que dans votre environnement de développement ! Elle ne doit pas être définie en production.

Vous pouvez obtenir une clé API gratuite et un identifiant de projet en créant un compte General Translation.

Après avoir créé un compte, rendez-vous sur la page Development API Keys pour obtenir votre clé API Dev et l'identifiant de votre projet.

Vous pouvez également utiliser la commande de l'outil CLI npx gtx-cli auth pour générer une clé API et un identifiant de projet pour votre projet, qui seront enregistrés dans votre fichier .env.local.

Utilisation

Super ! Si vous avez suivi les étapes ci-dessus, votre application Next.js est maintenant configurée pour utiliser gt-next.

L'étape suivante consiste à internationaliser votre contenu.
Ici, nous allons donner un bref aperçu des différentes façons de traduire le contenu dans votre application.

Composant `<T>`

Le composant <T> est le composant principal pour traduire le contenu JSX dans votre application.

Pour l'utiliser, il suffit d'entourer le JSX que vous souhaitez traduire avec le composant <T>.

import { T } from 'gt-next';
<T>
  <div>Votre contenu</div>
</T>

Si vous avez du contenu dynamique, vous devrez utiliser les composants de variable pour passer les valeurs dynamiques.

import { T, Var } from 'gt-next';

<T>
  <div>Bonjour, <Var>{name}</Var> !</div>
</T>

Consultez le guide Traduire du JSX pour plus d'informations.

Hook `useGT`

Le hook useGT est un hook React qui retourne une fonction pouvant être utilisée pour traduire des chaînes de caractères.

import { useGT } from 'gt-next/client';

const translate = useGT();
translate('Hello, world!');

Le hook useGT est un hook côté client, et doit uniquement être utilisé dans des composants côté client.
Pour les composants côté serveur, utilisez plutôt la fonction asynchrone getGT().

Consultez le guide Traduire des chaînes pour plus d'informations.

Utiliser la fonctionnalité de traduction avec rechargement à chaud sera utile pour internationaliser votre application.

Pour l'activer, assurez-vous d'avoir défini les variables d'environnement GT_API_KEY et GT_PROJECT_ID dans votre environnement de développement.

Tester votre application

Félicitations ! 🥳 Si vous avez suivi les étapes ci-dessus, votre application est maintenant multilingue ! Voyons-la en action.

Voir votre application dans une autre langue

Ajoutez le composant <LocaleSelector> à votre application. Cela vous permettra de sélectionner une langue différente pour votre application.

Astuce : Vous pouvez également ignorer cette étape et simplement changer la langue dans les paramètres de votre navigateur.

Démarrez votre application Next.js en mode développement.

npm run dev

yarn run dev

bun run dev

pnpm run dev

Ouvrez votre application dans votre navigateur préféré (généralement à l'adresse http://localhost:3000).

Dépannage

Déploiement

Super ! Si vous êtes satisfait de vos traductions et du fonctionnement de votre application, vous pouvez maintenant déployer votre application.

Le comportement de gt-next en production est légèrement différent de celui du développement. Plus précisément, aucune traduction ne sera effectuée à l'exécution (à l'exception du composant <Tx> et de la fonction tx).

Cela signifie que vous devrez traduire votre contenu avant de déployer votre application, lors du processus de build.

Heureusement, l'outil gtx-cli dispose d'une commande translate qui peut être utilisée pour traduire automatiquement votre contenu.

Tout d'abord, vous devrez obtenir une clé API de production depuis la General Translation platform.

Veuillez noter que cette clé est différente de votre clé API de développement, et commence par gtx-api-, au lieu de gtx-dev-.

Lisez la différence entre les clés de développement et de production ici.

Ajoutez cette variable d'environnement à votre pipeline CI/CD.

GT_PROJECT_ID=<your-project-id>
GT_API_KEY=<your-production-api-key>

Assurez-vous que GT_API_KEY n'est PAS préfixée par NEXT_PUBLIC_ !

Si c'est le cas, vous risquez d'exposer votre clé API au public.

Exécutez la commande translate pour traduire votre contenu.

npx gtx-cli translate

Vous pouvez configurer le comportement de la commande translate avec le fichier gt.config.json.

Consultez le guide de référence CLI Tool pour plus d'informations.

Ajoutez la commande translate à votre processus de build.

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

Résumé

Dans ce guide, nous avons expliqué comment configurer votre application Next.js avec gt-next
Nous avons brièvement abordé les différentes façons de traduire le contenu dans votre application.
Nous avons également vu comment déployer votre application après avoir internationalisé votre contenu.

Prochaines étapes

Découvrez comment traduire du contenu JSX avec le composant <T> : Traduire du JSX
Découvrez comment traduire des chaînes de caractères avec le hook useGT : Traduire des chaînes
Apprenez à utiliser les traductions locales : Traductions locales

Démarrage rapide avec Next.js

Que faire si je ne veux pas utiliser la plateforme General Translation ?

La langue de mon application ne change pas, même si j'ai changé la langue de mon navigateur.

Pourquoi les langues mettent-elles du temps à se charger en mode dev ?

Pourquoi certaines choses sont-elles traduites et d'autres non ?

Pourquoi certaines traductions sont-elles inexactes ?

Que faire si je n'utilise pas la General Translation platform ?

Sur cette page