# node: Démarrage rapide Node.js
URL: https://generaltranslation.com/fr/docs/node/tutorials/quickstart.mdx
---
title: Démarrage rapide Node.js
description: Ajoutez plusieurs langues à votre serveur Node.js en moins de 10 minutes
---

À la fin de ce guide, votre serveur Node.js renverra du contenu traduit selon la langue de la requête, à l’aide de chaînes de caractères en ligne ou préenregistrées.

**Prérequis :**

* Un serveur Node.js (Express, Fastify ou similaire)
* Node.js 18+

<Callout type="info">
  **Vous souhaitez une configuration automatique ?** Exécutez `npx gt@latest` pour tout configurer avec l’[assistant de configuration](/docs/cli/init). Ce guide explique la configuration manuelle.
</Callout>

***

## Étape 1 : Installez les paquets

`gt-node` est la bibliothèque qui gère les traductions sur votre serveur. `gt` est l’outil en ligne de commande qui prépare les traductions pour la production.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-node
    npm i -D gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-node
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-node
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-node
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

***

## Étape 2 : Créez un fichier de configuration de traduction

Créez un fichier **`gt.config.json`** à la racine de votre projet. Cela indique à la bibliothèque les langues que vous prenez en charge :

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"]
}
```

* **`defaultLocale`** — la langue dans laquelle sont écrites les chaînes de caractères de votre serveur.
* **`locales`** — les langues dans lesquelles vous souhaitez traduire. Choisissez-en dans la [liste des paramètres régionaux compatibles](/docs/platform/supported-locales).

***


## Étape 3 : Initialisez General Translation

Appelez **`initializeGT`** une seule fois en haut du fichier d’entrée de votre serveur, avant d’utiliser une fonction de traduction :

```js title="server.js"
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  projectId: process.env.GT_PROJECT_ID,
});
```

Cela configure la bibliothèque avec les langues prises en charge et les identifiants de votre projet.

***


## Étape 4 : Définir le contexte de paramètre régional pour chaque requête

Chaque requête doit savoir quelle langue utiliser. Utilisez **`withGT`** pour encapsuler vos gestionnaires de requêtes : il utilise le stockage local asynchrone afin que les fonctions de traduction récupèrent automatiquement le bon paramètre régional :

```js title="server.js"
import { withGT } from 'gt-node';

app.use((req, res, next) => {
  const locale = req.headers['accept-language']?.split(',')[0] || 'en';
  withGT(locale, () => next());
});
```

***


## Étape 5 : Traduire les chaînes de caractères en ligne

Pour traduire directement des chaînes de caractères dans les gestionnaires de requêtes, utilisez **`getGT`** :

```js title="server.js"
import { getGT } from 'gt-node';

app.get('/api/greeting', async (req, res) => {
  const gt = await getGT();
  res.json({
    message: gt('Hello, world!'),
    welcome: gt('Welcome, {name}!', { name: 'Alice' }),
  });
});
```

`getGT` renvoie une fonction de traduction liée au paramètre régional de la requête en cours.

***


## Étape 6 : Préenregistrer les chaînes de caractères constantes (facultatif)

Pour les chaînes de caractères définies en dehors des gestionnaires de requêtes — comme les messages d’erreur, les libellés d’énumération ou les constantes — utilisez **`msg`** pour les enregistrer au niveau du module, puis **`getMessages`** pour récupérer les traductions à l’exécution :

```js title="messages.js"
import { msg } from 'gt-node';

export const GREETING = msg('Hello, world!');
export const WELCOME = msg('Welcome, {name}!');
export const NOT_FOUND = msg('Resource not found.');
```

```js title="handler.js"
import { getMessages } from 'gt-node';
import { GREETING, WELCOME, NOT_FOUND } from './messages.js';

app.get('/api/status', async (req, res) => {
  const m = await getMessages();
  res.json({
    greeting: m(GREETING),
    welcome: m(WELCOME, { name: 'Alice' }),
  });
});

app.use(async (req, res) => {
  const m = await getMessages();
  res.status(404).json({ error: m(NOT_FOUND) });
});
```

Ce schéma est utile lorsque les mêmes chaînes de caractères sont utilisées dans plusieurs gestionnaires.

***


## Étape 7 : Configurer les variables d’environnement (facultatif)

Pour voir les traductions en développement, vous avez besoin de clés API de General Translation. Elles activent la **traduction on-demand** : votre serveur traduit le contenu en temps réel pendant que vous développez.

Créez un fichier **`.env`** :

```bash title=".env"
GT_API_KEY="your-api-key"
GT_PROJECT_ID="your-project-id"
```

Obtenez vos clés gratuites sur [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) ou en lançant :

```bash
npx gt auth
```

<Callout type="warn">
  N’exposez jamais `GT_API_KEY` publiquement et ne le versionnez jamais.
</Callout>

<Accordions>
  <Accordion title="Puis-je utiliser gt-node sans clé API ?">
    Oui. Sans clé API, `gt-node` fonctionne comme une bibliothèque i18n standard. Vous n’aurez pas de traduction on-demand en développement, mais vous pourrez quand même :

    * Fournir manuellement vos propres fichiers de traduction
    * Utiliser toutes les fonctions de traduction (`getGT`, `msg`, `getMessages`, etc.)
    * Exécuter `npx gt generate` pour créer des templates de fichiers de traduction, puis les traduire vous-même
  </Accordion>
</Accordions>

***


## Étape 8 : Vérifiez que cela fonctionne

Démarrez votre serveur et testez avec différents en-têtes `Accept-Language` :

```bash
# Par défaut (anglais)
curl http://localhost:3000/api/greeting

# Espagnol
curl -H "Accept-Language: es" http://localhost:3000/api/greeting

# Français
curl -H "Accept-Language: fr" http://localhost:3000/api/greeting
```

Vous devriez voir des réponses traduites pour chaque langue.

<Callout type="info">
  En développement, les traductions se font on-demand — vous pourriez remarquer un léger délai la première fois qu’une nouvelle langue est demandée. En production, les traductions sont pré-générées et se chargent instantanément.
</Callout>

***


## Étape 9 : Exemple complet

Voici un exemple complet de serveur Express avec tous les éléments réunis :

```js title="server.js"
import express from 'express';
import { initializeGT, withGT, getGT, msg, getMessages } from 'gt-node';

// Initialiser GT avant tout le reste
initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  projectId: process.env.GT_PROJECT_ID,
});

// Pré-enregistrer les chaînes de caractères constantes
const NOT_FOUND = msg('Resource not found.');

const app = express();

// Définir le contexte de paramètre régional pour chaque requête
app.use((req, res, next) => {
  const locale = req.headers['accept-language']?.split(',')[0] || 'en';
  withGT(locale, () => next());
});

// Traduction en ligne
app.get('/api/greeting', async (req, res) => {
  const gt = await getGT();
  res.json({ message: gt('Hello, world!') });
});

// Traduction de message pré-enregistré
app.use(async (req, res) => {
  const m = await getMessages();
  res.status(404).json({ error: m(NOT_FOUND) });
});

app.listen(3000, () => console.log('Server running on port 3000'));
```

***


## Étape 10 : Déployer en production

En production, les traductions sont générées à l’avance au moment du 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 && <YOUR_BUILD_COMMAND>"
  }
}
```

Définissez vos variables d’environnement de **production** dans votre hébergeur :

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

<Callout type="warn">
  N’exposez jamais votre `GT_API_KEY` publiquement.
</Callout>

C&#39;est tout — votre serveur est maintenant multilingue. 🎉

***


## Dépannage

<Accordions>
  <Accordion title="Les traductions sont lentes en développement">
    C’est normal. En développement, les traductions se font on-demand (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`.
  </Accordion>

  <Accordion title="Certaines traductions sont inexactes">
    Un texte ambigu peut entraîner des traductions inexactes. Par exemple, &quot;apple&quot; peut désigner le fruit ou l’entreprise. Ajoutez l’option `$context` pour préciser le contexte :

    ```js
    gt('Apple', { $context: 'the technology company' });
    ```

    `getGT()` et `msg()` prennent tous deux en charge l’option `$context`.
  </Accordion>
</Accordions>

***

## Étapes suivantes

* [**`initializeGT`**](/docs/node/api/initialize-gt) — Options de configuration complètes
* [**`withGT`**](/docs/node/api/with-gt) — Contexte de paramètre régional des requêtes
* [**`getGT`**](/docs/node/api/get-gt) — Traduction en ligne de chaînes de caractères
* [**`msg` &amp; `getMessages`**](/docs/node/api/get-messages) — Traduction de messages préenregistrés
* [**CLI**](/docs/cli/translate) — Référence du workflow de traduction