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

title: formatMessage
description: Formatez des messages au format ICU sans instance GT. Référence d’API pour formatMessage.

---

[`formatMessage`](/docs/platform/core/reference/gt-class-methods/formatting/format-message) est une fonction utilitaire autonome de la bibliothèque Core de General Translation qui formate des messages avec substitution de variables et un formatage adapté au paramètre régional. Elle prend en charge la syntaxe du format de message ICU, ce qui en fait l’outil principal pour l’interpolation de variables et la pluralisation.

## Vue d’ensemble [#overview]

Importez `formatMessage` directement depuis `generaltranslation` et appelez `formatMessage` avec une chaîne de message et un objet d’options. Elle ne nécessite ni clé API ni instance de [GT](/docs/platform/core/reference/gt-class/constructor). Pour un formatage basé sur une instance et héritant du paramètre régional de celle-ci, utilisez plutôt la méthode [`formatMessage`](/docs/platform/core/reference/gt-class-methods/formatting/format-message) sur une instance de [`GT`](/docs/platform/core/reference/gt-class/constructor).

Elle s’appuie sur la bibliothèque [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) de Format.JS et prend donc également en charge le formatage des nombres, des dates, les pluriels et les sélections.

```typescript
import { formatMessage } from 'generaltranslation';

const formatted = formatMessage('Hello {name}, you have {count} messages', {
  locales: ['en'],
  variables: { name: 'Alice', count: 5 },
});
// Retourne : "Hello Alice, you have 5 messages"
```

Signature :

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

## Fonctionnement [#how-it-works]

* **Gestion des paramètres régionaux.** Utilise les `locales` fournies pour le formatage et revient à `'en'` si aucune n’est spécifiée. Les tableaux servent de chaîne de secours pour les paramètres régionaux.
* **Traitement des variables.** Les variables sont injectées dans le message. Les espaces réservés simples `{variable}` sont remplacés par leurs valeurs ; le format de message ICU est entièrement pris en charge pour les pluriels, les sélections et le formatage.
* **Format des données.** `dataFormat` vaut par défaut `'ICU'`. Lorsqu’il est défini sur `'STRING'`, le message est renvoyé tel quel, sans interprétation ICU.
* **Prise en charge du format de message.** Les mêmes fonctionnalités ICU que dans la méthode de la classe GT sont disponibles : formatage des nombres (`{price, number, ::currency/USD}`), formatage des dates (`{date, date, short}`), pluralisation (`{count, plural, ...}`) et sélection (`{gender, select, ...}`).
* **Pas de traduction.** Cette fonction met en forme et interpole un message ; elle ne traduit pas le texte du message lui-même. Seules les valeurs des variables et le résultat ICU s’adaptent au paramètre régional.

## Paramètres [#parameters]

| Paramètre             | Description                                                                                   | Type     | Facultatif | Par défaut |
| --------------------- | --------------------------------------------------------------------------------------------- | -------- | ---------- | ---------- |
| [`message`](#message) | Le message à mettre en forme.                                                                 | `string` | Non        | —          |
| [`options`](#options) | Configuration du formatage, y compris le ou les paramètres régionaux cibles et les variables. | `object` | Oui        | `{}`       |

### `message` [#message]

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

La chaîne de message à formater. Elle peut contenir des motifs au format de message ICU. Une chaîne vide renvoie une chaîne vide.

### `options` [#options]

**Type** `object` · **Facultatif** · **Par défaut** `{}`

Configuration du formatage :

| Propriété    | Description                                                        | Type                             | Facultatif | Par défaut |
| ------------ | ------------------------------------------------------------------ | -------------------------------- | ---------- | ---------- |
| `locales`    | Paramètres régionaux à utiliser pour le formatage.                 | `string \| string[]`             | Oui        | `'en'`     |
| `variables`  | Objet contenant les variables d’interpolation.                     | `FormatVariables`                | Oui        | `{}`       |
| `dataFormat` | Format du message. Si `'STRING'`, le message est renvoyé tel quel. | `'ICU' \| 'I18NEXT' \| 'STRING'` | Oui        | `'ICU'`    |

## Renvoie [#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
import { formatMessage } from 'generaltranslation';

// Utilisation de base
const greeting = formatMessage('Hello {name}!', {
  locales: ['en'],
  variables: { name: 'World' },
});
console.log(greeting); // "Hello World!"
```

```typescript
// Fonction utilitaire pour le formatage sans instanciation de classe
function quickFormat(
  template: string,
  variables: Record<string, unknown>,
  locale = 'en'
) {
  return formatMessage(template, {
    locales: [locale],
    variables,
  });
}

const notification = quickFormat(
  'You have {count, plural, =0 {no messages} =1 {one message} other {# messages}}',
  { count: 3 },
  'en'
);
console.log(notification); // "You have 3 messages"
```

```typescript
// Formatage des devises et des nombres

// Formatage avec le paramètre régional allemand (la devise nécessite un skeleton de devise)
const germanPrice = formatMessage('Preis: {price, number, ::currency/EUR}', {
  locales: ['de'],
  variables: { price: 1234.56 },
});
console.log(germanPrice); // "Preis: 1.234,56 €"

// Formatage en pourcentage
const progress = formatMessage('Progress: {percent, number, percent}', {
  locales: ['en'],
  variables: { percent: 0.85 },
});
console.log(progress); // "Progress: 85%"
```

```typescript
import { formatMessage } from 'generaltranslation';

// Modèles de messages réutilisables
class MessageTemplates {
  private locale: string;

  constructor(locale: string = 'en') {
    this.locale = locale;
  }

  welcome(name: string) {
    return formatMessage('Welcome back, {name}!', {
      locales: [this.locale],
      variables: { name },
    });
  }

  itemCount(count: number) {
    return formatMessage(
      '{count, plural, =0 {No items} =1 {One item} other {# items}}',
      {
        locales: [this.locale],
        variables: { count },
      }
    );
  }
}

const templates = new MessageTemplates('fr');
// Remarque : formatMessage ne traduit pas le texte — seules les règles de pluriel/format ICU
// suivent le paramètre régional ; le texte anglais littéral est donc renvoyé tel quel.
console.log(templates.welcome('Marie')); // "Welcome back, Marie!"
console.log(templates.itemCount(5)); // "5 items"
```

## Notes [#notes]

* Nécessite de spécifier explicitement le paramètre régional dans les options pour les paramètres régionaux autres que le paramètre régional par défaut ; sinon, la valeur de repli est `'en'`.
* Prend en charge les mêmes fonctionnalités du format de message ICU que la méthode de la classe GT.
* Retourne une chaîne vide lorsque les templates d’entrée sont vides.
* Les variables sont traitées selon les règles de formatage ICU ; si une variable à laquelle il est fait référence n’est pas fournie, une erreur `MISSING_VALUE` est générée.