# General Translation Platform: formatMessage
URL: https://generaltranslation.com/fr/docs/platform/core/reference/gt-class-methods/formatting/format-message.mdx
---

title: formatMessage
description: Formate des messages au format ICU avec des variables et des valeurs adaptées au paramètre régional. Référence de l’API pour formatMessage.

---

Formate un message avec substitution de variables et formatage adapté au paramètre régional sur une instance de [GT](/docs/platform/core/reference/gt-class/constructor). General Translation s’appuie sur la bibliothèque [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) de Format.JS pour prendre en charge les modèles du format de message ICU, notamment l’interpolation de variables, la pluralisation, le formatage des nombres et des dates.

## Vue d’ensemble [#overview]

Appelez `formatMessage` sur une instance de [`GT`](/docs/platform/core/reference/gt-class/constructor) avec une chaîne de message et, éventuellement, un objet d’options contenant les `variables` à interpoler. Elle renvoie le message formaté.

```typescript
const gt = new GT({ sourceLocale: 'en', targetLocale: 'fr' });

const formatted = gt.formatMessage('Hello {name}, you have {count} messages', {
  variables: { name: 'Alice', count: 5 },
});
// "Hello Alice, vous avez 5 messages"
```

Signature :

```typescript
formatMessage(
  message: string,
  options?: {
    locales?: string | string[];
    variables?: FormatVariables;
    dataFormat?: StringFormat;
  }
): string
```

*Remarque : `formatMessage` s’exécute localement avec `IntlMessageFormat` (issu de `intl-messageformat`) et ne nécessite pas de clé API. Il remplace les paramètres régionaux de l’instance lorsque `locales` est fourni. Pour effectuer un formatage sans instance `GT`, consultez la version autonome de [`formatMessage`](/docs/platform/core/reference/utility-functions/formatting/format-message).*

## Fonctionnement [#how-it-works]

* **Traitement ICU.** La méthode analyse la syntaxe du format de message ICU avec `IntlMessageFormat` (issu de `intl-messageformat`) et applique automatiquement le formatage des nombres, des dates et des devises selon le paramètre régional.
* **Résolution du paramètre régional.** `locales` remplace les valeurs par défaut de l’instance pour un appel unique.
* **Les variables manquantes provoquent une erreur.** Si le message référence une variable qui n’est pas fournie dans `variables`, une erreur est générée.
* **Échappement des accolades.** Conformément à la syntaxe ICU, entourez une accolade littérale de guillemets simples (`'{'` ou `'}'`) afin qu’elle ne soit pas interprétée comme le début d’un substitut.

### Substitution de variables

* Variables simples : `{variableName}` est remplacé par une chaîne de caractères.
* Modèles ICU : `{count, plural, ...}` sont traités selon les règles de formatage ICU.
* Variables manquantes : provoquent une erreur.
* Accolades littérales : entourez-les de guillemets simples selon la syntaxe ICU (`'{'` ou `'}'`) pour afficher une accolade littérale.

### Prise en charge du format de message

* **Interpolation simple :** `{variable}`
* **Formatage des nombres :** `{price, number, ::currency/USD}`, `{discount, number, percent}`, `{num, number, integer}`
* **Formatage des dates :** `{date, date, short}`, `{time, time, short}`
* **Pluralisation :** `{count, plural, =0 {none} =1 {one} other {many}}`
* **Sélection :** `{gender, select, male {he} female {she} other {they}}`
* **Selectordinal :** `{place, selectordinal, =1 {#st} =2 {#nd} =3 {#rd} other {#th}}`

## Paramètres [#parameters]

| Paramètre             | Description                                          | Type     | Facultatif | Par défaut |
| --------------------- | ---------------------------------------------------- | -------- | ---------- | ---------- |
| [`message`](#message) | Le message de style ICU à formater.                  | `string` | Non        | —          |
| [`options`](#options) | Configuration de formatage, y compris les variables. | `object` | Oui        | —          |

### `message` [#message]

**Type** `string` · **Obligatoire**

Le message à formater, à l’aide de la syntaxe du format de message ICU.

### `options` [#options]

**Type** `object` · **Facultatif**

Configuration du formatage :

| Nom          | Description                                                                                          | Type                 | Facultatif | Par défaut                         |
| ------------ | ---------------------------------------------------------------------------------------------------- | -------------------- | ---------- | ---------------------------------- |
| `locales`    | Paramètres régionaux à utiliser pour le formatage (remplacent les valeurs par défaut de l’instance). | `string \| string[]` | Oui        | paramètres régionaux de l’instance |
| `variables`  | Objet de variables pour l’interpolation des messages.                                                | `FormatVariables`    | Oui        | `{}`                               |
| `dataFormat` | Format de données de la chaîne du message (`'ICU'`, `'I18NEXT'` ou `'STRING'`).                      | `StringFormat`       | Oui        | `'ICU'`                            |

Le type `FormatVariables` :

```typescript
type FormatVariables = Record<string, string | number | boolean | null | undefined | Date>;
```

## Valeur renvoyée [#returns]

**Type** `string`

Le message formaté, avec les variables remplacées et la mise en forme propre au paramètre régional appliquée.

## Exemples [#examples]

```typescript
// Substitution de variables de base
const gt = new GT({ targetLocale: 'en' });

const message = gt.formatMessage('Welcome {name}!', {
  variables: { name: 'John' },
});
console.log(message); // "Welcome John!"
```

```typescript
// Pluralisation avec le format ICU
const message = gt.formatMessage(
  'You have {count, plural, =0 {no items} =1 {one item} other {# items}} in your cart',
  {
    variables: { count: 3 },
  }
);
console.log(message); // "You have 3 items in your cart"
```

```typescript
// Formatage des nombres et des devises
const gt = new GT({ targetLocale: 'en' });

const message = gt.formatMessage(
  'Your total is {price, number, ::currency/USD} with {discount, number, percent} off',
  {
    variables: {
      price: 99.99,
      discount: 0.15,
    },
  }
);
console.log(message); // "Your total is $99.99 with 15% off"
```

```typescript
// Modèles de messages complexes
const orderStatusMessage = gt.formatMessage(`
  Order #{orderId} status update:
  - Items: {itemCount, plural, =0 {no items} =1 {one item} other {# items}}
  - Total: {total, number, ::currency/USD}
  - Status: {status, select,
      pending {Pending}
      shipped {Shipped}
      delivered {Delivered}
      other {Unknown}}
  - Delivery: {deliveryDate, date, short}
`, {
  variables: {
    orderId: 'ORD-12345',
    itemCount: 3,
    total: 149.97,
    status: 'shipped',
    deliveryDate: new Date('2024-03-20'),
  },
});
```

## Remarques [#notes]

* La méthode traite la syntaxe du format de message ICU avec `IntlMessageFormat` (de `intl-messageformat`).
* Les variables manquantes provoquent une erreur.
* Le formatage spécifique au paramètre régional des nombres, des dates et des devises est appliqué automatiquement.
* Pour formater des nombres seuls, utilisez [`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num).