# node: Approches de traduction de chaînes de caractères
URL: https://generaltranslation.com/fr/docs/node/guides/strings.mdx
---
title: Approches de traduction de chaînes de caractères
description: Deux approches pour traduire des chaînes de caractères dans Node.js — en ligne et pré-enregistrées
---

Il existe trois façons de traduire des chaînes de caractères dans `gt-node` :

1. **En ligne avec `getGT()`** — traduisez les chaînes de caractères directement dans les gestionnaires de requêtes (build)
2. **Pré-enregistrées avec `msg()` / `getMessages()`** — définissez les chaînes de caractères dans l’ambito du module, puis résolvez-les à l’exécution (build)
3. **On-demand avec `tx()`** — traduisez les chaînes de caractères à l’exécution, y compris le contenu qui n’est pas connu au build

## Traduction en ligne avec `getGT()`

Utilisez [`getGT()`](/docs/node/api/get-gt) lorsque la chaîne de caractères n’est utilisée qu’à un seul endroit, ou lorsque le contenu dépend de données propres à la requête :

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

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


### Interpolation de variables

Passez les variables en second argument à l’aide des placeholders `{name}` :

```js
const gt = await getGT();

gt('Welcome, {name}!', { name: user.displayName });
gt('You have {count} new messages.', { count: unreadCount });
gt('{city} weather: {temp}°F', { city: 'Tokyo', temp: 72 });
```


## Chaînes de caractères pré-enregistrées avec `msg()` / `getMessages()`

Utilisez [`msg()`](/docs/node/api/get-messages) pour enregistrer des chaînes de caractères au niveau du module — en dehors de tout gestionnaire de requête. Utilisez ensuite [`getMessages()`](/docs/node/api/get-messages) dans les gestionnaires pour les résoudre selon le paramètre régional actuel :

```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.');
export const UNAUTHORIZED = msg('You must be logged in.');
```

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

app.get('/api/greeting', 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) });
});
```

Cette approche est particulièrement adaptée lorsque :

* La même chaîne de caractères est utilisée dans plusieurs gestionnaires
* Les chaînes de caractères sont des constantes partagées (messages d’erreur, libellés, énumérations)
* Vous souhaitez regrouper toutes les chaînes traduisibles dans un seul fichier pour en faciliter la révision

## Traduction on-demand avec `tx()`

Utilisez [`tx()`](/docs/node/api/strings/tx) lorsque le contenu n’est pas connu au moment du build — par exemple, du contenu généré par les utilisateurs ou des données dynamiques qui ne peuvent pas être pré-traduites :

```js title="routes/translate.js"
import { tx } from 'gt-node';

app.post('/api/translate', async (req, res) => {
  const translated = await tx(req.body.text);
  res.json({ translated });
});
```

`tx` est asynchrone et effectue la traduction à la demande via une requête réseau ; il est donc plus lent que les approches au build. Utilisez-le uniquement lorsque `getGT()` ou `msg()` ne peuvent pas couvrir ce cas d’usage.

## Quand utiliser l’une ou l’autre

| Approche                  | Idéal pour                                                                                                                 |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `getGT()`                 | Chaînes de caractères ponctuelles, contenu propre à une requête, chaînes de caractères utilisées dans un seul gestionnaire |
| `msg()` / `getMessages()` | Constantes partagées, messages d’erreur, libellés d’énumération, gestion centralisée des chaînes de caractères             |
| `tx()`                    | Contenu dynamique ou généré par les utilisateurs, non connu au moment du build                                             |

<Callout>
  Les deux approches produisent des traductions identiques. La seule différence concerne l’organisation du code — choisissez celle qui s’adapte le mieux à la structure de votre projet.
</Callout>

## Utiliser `$context` pour lever les ambiguïtés

Les chaînes de caractères ambiguës peuvent entraîner des traductions inexactes. Ajoutez `$context` pour guider le traducteur :

```js
// En ligne
const gt = await getGT();
gt('Apple', { $context: 'the technology company' });
gt('Spring', { $context: 'the season, not a coil' });

// Pré-enregistré
const APPLE = msg('Apple', { $context: 'the fruit' });
const SPRING = msg('Spring', { $context: 'a metal coil' });
```


## Exemple complet

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

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

// Pré-enregistrer les chaînes de caractères partagées
const ERRORS = {
  notFound: msg('Resource not found.'),
  unauthorized: msg('You must be logged in.'),
  forbidden: msg('You do not have permission to access this resource.'),
};

const app = express();

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

// Traduction en ligne
app.get('/api/dashboard', async (req, res) => {
  const gt = await getGT();
  res.json({
    title: gt('Dashboard'),
    subtitle: gt('Welcome back, {name}!', { name: req.user.name }),
  });
});

// Messages pré-enregistrés
app.use(async (req, res) => {
  const m = await getMessages();
  res.status(404).json({ error: m(ERRORS.notFound) });
});

app.listen(3000);
```


## Prochaines étapes

* [Référence de l’API `getGT`](/docs/node/api/get-gt)
* [Référence de l’API `msg` et `getMessages`](/docs/node/api/get-messages)
* [Référence de l’API `tx`](/docs/node/api/strings/tx) — traduction en exécution
* [Détection du paramètre régional et middleware](/docs/node/guides/middleware) — fonctionnement du contexte du paramètre régional