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

title: formatNum
description: Met en forme les nombres, la Currency, les pourcentages et les valeurs numériques sans instance GT. Référence d’API pour formatNum.

---

[`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num) est une fonction utilitaire autonome de la bibliothèque Core de General Translation qui met en forme les nombres selon les conventions propres au paramètre régional. Elle renvoie une chaîne adaptée au paramètre régional pour les décimales, la Currency, les pourcentages et les unités.

## Aperçu [#overview]

Importez `formatNum` directement depuis `generaltranslation` et appelez-le avec le nombre à formater et un objet d’options. Il ne nécessite ni clé API ni instance [GT](/docs/platform/core/reference/gt-class/constructor), vous pouvez donc l’utiliser partout où vous avez besoin d’un formatage ponctuel de nombres. Pour un formatage basé sur une instance qui hérite du paramètre régional de l’instance, utilisez plutôt la méthode [`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num) sur une instance [`GT`](/docs/platform/core/reference/gt-class/constructor).

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

const formatted = formatNum(1234.56, {
  locales: 'de-DE',
  style: 'currency',
  currency: 'EUR',
});
// Retourne : "1.234,56 €"
```

Signature :

```typescript
formatNum(
  number: number,
  options?: { locales?: string | string[] } & Intl.NumberFormatOptions
): string
```

## Fonctionnement [#how-it-works]

* **API sous-jacente.** Utilise le même [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) que la méthode de la classe GT ; toutes les options standard de `Intl.NumberFormat` sont donc prises en charge.
* **Résolution du paramètre régional.** Lorsque `locales` est un tableau, les paramètres régionaux sont testés dans l’ordre, et le premier paramètre régional pris en charge est utilisé. Lorsque `locales` est omis, la valeur de repli est le paramètre régional par défaut de la bibliothèque, `en`.
* **Mise en cache.** Les résultats sont mis en cache en interne afin d’améliorer les performances pour les combinaisons répétées de paramètres régionaux et d’options.

## Paramètres [#parameters]

| Paramètre             | Description                                                                                                     | Type                                                          | Facultatif | Par défaut |
| --------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------- | ---------- |
| [`number`](#number)   | Le nombre à formater.                                                                                           | `number`                                                      | Non        | —          |
| [`options`](#options) | Configuration du formatage, y compris le ou les paramètres régionaux cibles et les options `Intl.NumberFormat`. | `{ locales?: string \| string[] } & Intl.NumberFormatOptions` | Oui        | `{}`       |

### `number` [#number]

**Type** `number` · **Obligatoire**

La valeur numérique à mettre en forme.

### `options` [#options]

**Type** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **Facultatif** · **Par défaut** `{}`

Configuration du formatage. Toute option de [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) est acceptée en plus de `locales`. Voici les champs les plus courants :

| Propriété               | Description                                                                                              | Type                                                       | Facultatif | Par défaut   |
| ----------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------- | ------------ |
| `locales`               | Paramètre(s) régional(aux) pour le formatage. Si un array est fourni, ils sont essayés dans l'ordre. | `string \| string[]`                                       | Oui        | `en`         |
| `style`                 | Style de formatage des nombres.                                                                          | `'decimal' \| 'currency' \| 'percent' \| 'unit'`           | Oui        | `'decimal'`  |
| `currency`              | Code de devise (obligatoire lorsque `style` vaut `'currency'`).                                          | `string`                                                   | Oui        | —            |
| `minimumIntegerDigits`  | Nombre minimal de chiffres entiers (1–21).                                                               | `number`                                                   | Oui        | —            |
| `minimumFractionDigits` | Nombre minimal de chiffres après la virgule (0–20).                                                      | `number`                                                   | Oui        | —            |
| `maximumFractionDigits` | Nombre maximal de chiffres après la virgule (0–20).                                                      | `number`                                                   | Oui        | —            |
| `useGrouping`           | Indique s'il faut utiliser des séparateurs de groupes.                                               | `boolean \| 'always' \| 'auto' \| 'min2'`                  | Oui        | `'auto'`     |
| `notation`              | Format de notation des nombres.                                                                          | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Oui        | `'standard'` |

## Valeur de retour [#returns]

**Type** `string`

Le nombre mis en forme conformément aux conventions du paramètre régional.

## Exemples [#examples]

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

// Formatage de nombre de base
console.log(formatNum(1234.567, { locales: 'en-US' }));
// Résultat : "1,234.567"

// Formatage allemand
console.log(formatNum(1234.567, { locales: 'de-DE' }));
// Résultat : "1.234,567"
```

```typescript
// Formatage de devise

// Dollar américain
console.log(formatNum(1234.56, {
  locales: 'en-US',
  style: 'currency',
  currency: 'USD',
}));
// Résultat : "$1,234.56"

// Euro avec le paramètre régional allemand
console.log(formatNum(1234.56, {
  locales: 'de-DE',
  style: 'currency',
  currency: 'EUR',
}));
// Résultat : "1.234,56 €"

// Yen japonais
console.log(formatNum(1234.56, {
  locales: 'ja-JP',
  style: 'currency',
  currency: 'JPY',
}));
// Résultat : "¥1,235"
```

## Remarques [#notes]

* Utilise le même `Intl.NumberFormat` sous-jacent que la méthode de la classe GT.
* Les résultats sont mis en cache en interne afin d’améliorer les performances lorsque les mêmes combinaisons de paramètre régional et d’options sont réutilisées.
* Les paramètres régionaux de secours sont traités dans l’ordre si le paramètre régional principal n’est pas pris en charge.
* Toutes les options standard de `Intl.NumberFormat` sont prises en charge.