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

title: formatMessage
description: Formatta messaggi in stile ICU con variabili e valori dipendenti dall'impostazione regionale. API Reference di formatMessage.

---

Formatta un messaggio con la sostituzione di variabili e la formattazione in base all'impostazione regionale in un'istanza di [GT](/docs/platform/core/reference/gt-class/constructor). General Translation si basa sulla libreria [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) di Format.JS per supportare i pattern ICU MessageFormat, inclusi l'interpolazione delle variabili, la pluralizzazione, la formattazione dei numeri e delle date.

## Panoramica [#overview]

Chiama `formatMessage` su un'istanza di [`GT`](/docs/platform/core/reference/gt-class/constructor) con una stringa contenente il messaggio e un oggetto options facoltativo che contiene le `variables` da interpolare. Restituisce il messaggio formattato.

```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, you have 5 messages"
```

Firma:

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

*Nota: `formatMessage` viene eseguito localmente tramite `IntlMessageFormat` (da `intl-messageformat`) e non richiede una chiave API. Sostituisce le impostazioni regionali dell'istanza quando viene specificato `locales`. Per la formattazione senza un'istanza `GT`, vedi [`formatMessage`](/docs/platform/core/reference/utility-functions/formatting/format-message) standalone.*

## Come funziona [#how-it-works]

* **Elaborazione ICU.** Il metodo analizza la sintassi di ICU MessageFormat con `IntlMessageFormat` (da `intl-messageformat`) e applica automaticamente la formattazione specifica dell'impostazione regionale per numeri, date e Currency.
* **Risoluzione delle impostazioni regionali.** `locales` sovrascrive i valori predefiniti dell'istanza per una singola chiamata.
* **Le variabili mancanti generano un errore.** Se nel messaggio viene fatto riferimento a una variabile non fornita in `variables`, viene generato un errore.
* **Escape delle parentesi graffe.** In base alla sintassi ICU, racchiudi una parentesi graffa letterale tra apici singoli (`'{'` o `'}'`) così non viene interpretata come l'inizio di un segnaposto.

### Sostituzione delle variabili

* Variabili semplici: `{variableName}` viene sostituito con il valore della stringa.
* Pattern ICU: `{count, plural, ...}` viene elaborato secondo le regole di formattazione ICU.
* Variabili mancanti: generano un errore.
* Parentesi graffe letterali: racchiudile tra apici singoli seguendo la sintassi ICU (`'{'` o `'}'`) per visualizzare una parentesi graffa letterale.

### Supporto per il formato dei messaggi

* **Interpolazione semplice:** `{variable}`
* **Formattazione dei numeri:** `{price, number, ::currency/USD}`, `{discount, number, percent}`, `{num, number, integer}`
* **Formattazione di data e ora:** `{date, date, short}`, `{time, time, short}`
* **Pluralizzazione:** `{count, plural, =0 {none} =1 {one} other {many}}`
* **Selezione:** `{gender, select, male {he} female {she} other {they}}`
* **Selectordinal:** `{place, selectordinal, =1 {#st} =2 {#nd} =3 {#rd} other {#th}}`

## Parametri [#parameters]

| Parametro             | Descrizione                                               | Type      | Facoltativo | Predefinito |
| --------------------- | --------------------------------------------------------- | --------- | ----------- | ----------- |
| [`message`](#message) | Il messaggio in formato ICU da formattare.                | `stringa` | No          | —           |
| [`options`](#options) | Configurazione della formattazione, incluse le variabili. | `object`  | Sì          | —           |

### `message` [#message]

**Tipo** `stringa` · **Obbligatorio**

Il messaggio da formattare, usando la sintassi di ICU MessageFormat.

### `options` [#options]

**Type** `object` · **Facoltativo**

Configurazione della formattazione:

| Name         | Description                                                                                                 | Type                 | Optional | Default                  |
| ------------ | ----------------------------------------------------------------------------------------------------------- | -------------------- | -------- | ------------------------ |
| `locales`    | Impostazioni regionali da usare per la formattazione (sovrascrivono i valori predefiniti dell'istanza). | `string \| string[]` | Sì       | locales dell'istanza |
| `variables`  | Oggetto contenente le variabili per l'interpolazione del messaggio.                                     | `FormatVariables`    | Sì       | `{}`                     |
| `dataFormat` | Formato dei dati della stringa del messaggio (`'ICU'`, `'I18NEXT'` o `'STRING'`).                           | `StringFormat`       | Sì       | `'ICU'`                  |

Il tipo `FormatVariables`:

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

## Restituisce [#returns]

**Tipo** `string`

Il messaggio formattato, con le variabili sostituite e la formattazione specifica dell&#39;impostazione regionale applicata.

## Esempi [#examples]

```typescript
// Sostituzione di variabili di base
const gt = new GT({ targetLocale: 'en' });

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

```typescript
// Pluralizzazione con formato 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
// Formattazione di numeri e valute
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
// Template di messaggi complessi
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'),
  },
});
```

## Note [#notes]

* Il metodo gestisce la sintassi ICU MessageFormat con `IntlMessageFormat` (da `intl-messageformat`).
* Le variabili mancanti generano un errore.
* La formattazione di numeri, date e Currency specifica dell&#39;impostazione regionale viene applicata automaticamente.
* Per formattare numeri standalone, usa [`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num).