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 aurez une application Next.js prête à commencer la traduction de contenu.

Dans ce guide, nous couvrirons les points suivants :

Installation

Configuration

Utilisation

Test de 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 qui est 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 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 travaillent ensemble pour fournir un contexte à votre application.

Ce contexte inclut :

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

D'abord, ajoutez le composant GTProvider au layout racine de votre application. Il devrait ê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 racine, 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 devriez personnaliser defaultLocale et locales pour correspondre à votre projet. Consultez la liste des locales supportées 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="" # Your General Translation Developer API key
GT_PROJECT_ID="" # Your General Translation project ID

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

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

Après avoir créé un compte, naviguez vers la page Clés API de développement pour obtenir votre clé API de développement et votre ID de projet.

Alternativement, vous pouvez également utiliser la commande de l'outil CLI npx gtx-cli auth pour générer une clé API et un ID de projet pour votre projet, sauvegardés dans votre fichier .env.local.

Utilisation

Parfait ! 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 donnerons 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, enveloppez simplement le JSX que vous voulez traduire dans le composant <T>.

import { T } from 'gt-next';
<T>
  <div>Your content</div>
</T>

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

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

<T>
  <div>Hello, <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 qui peut ê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 ne devrait être utilisé que 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 de caractères pour plus d'informations.

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

Pour activer cela, assurez-vous d'avoir les variables d'environnement GT_API_KEY et GT_PROJECT_ID définies 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 autre langue 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

Parfait ! Si vous êtes satisfait de vos traductions et de la fonctionnalité de votre application, vous pouvez maintenant déployer votre application.

Le comportement de gt-next en production est légèrement différent 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, dans le 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 plateforme General Translation.

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 à propos de 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 avec 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 de l'Outil CLI 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 couvert comment configurer votre application Next.js avec gt-next
Nous avons brièvement couvert les différentes façons de traduire le contenu dans votre application.
Nous avons également couvert comment déployer votre application après avoir internationalisé votre contenu.

Prochaines étapes

Apprenez comment traduire le contenu JSX avec le composant <T> : Traduire du JSX
Apprenez comment traduire des chaînes de caractères avec le hook useGT : Traduire des chaînes
Apprenez comment 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 ?

Et si je n'utilise pas la plateforme General Translation ?

Sur cette page