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

title: formatMessage
description: Formatta messaggi in stile ICU senza un'istanza GT. Riferimento API per formatMessage.

---

[`formatMessage`](/docs/platform/core/reference/gt-class-methods/formatting/format-message) è una funzione di utilità autonoma della libreria Core di General Translation che formatta i messaggi con la sostituzione delle variabili e una formattazione basata sull'impostazione regionale. Supporta i pattern del formato di messaggi ICU, ed è quindi lo strumento principale per l'interpolazione delle variabili e la pluralizzazione.

## Panoramica [#overview]

Importa `formatMessage` direttamente da `generaltranslation` e chiamalo con una stringa del messaggio e un oggetto options. Non richiede una chiave API né un'istanza di [GT](/docs/platform/core/reference/gt-class/constructor). Per una formattazione basata su un'istanza che eredita l'impostazione regionale dell'istanza, usa invece il metodo [`formatMessage`](/docs/platform/core/reference/gt-class-methods/formatting/format-message) su un'istanza di [`GT`](/docs/platform/core/reference/gt-class/constructor).

Si basa sulla libreria [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) di Format.JS, quindi supporta anche la formattazione di numeri e date, i plurali e i selettori.

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

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

Firma:

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

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

* **Gestione delle impostazioni regionali.** Usa i `locales` forniti per la formattazione, con fallback a `'en'` quando non ne viene specificato nessuno. Gli array fungono da catena di fallback per le impostazioni regionali.
* **Elaborazione delle variabili.** Le variabili vengono sostituite nel messaggio. I placeholder semplici `{variable}` vengono rimpiazzati con i rispettivi valori; il formato ICU MessageFormat è pienamente supportato per plurali, selezioni e formattazione.
* **Formato dei dati.** `dataFormat` è impostato su `'ICU'` per impostazione predefinita. Quando è impostato su `'STRING'`, il messaggio viene restituito così com'è, senza parsing ICU.
* **Supporto del formato del messaggio.** Sono disponibili le stesse funzionalità ICU del metodo della classe GT: formattazione dei numeri (`{price, number, ::currency/USD}`), formattazione delle date (`{date, date, short}`), pluralizzazione (`{count, plural, ...}`) e selezione (`{gender, select, ...}`).
* **Nessuna traduzione.** Questa funzione formatta e interpola un messaggio; non traduce il testo del messaggio stesso. Solo i valori delle variabili e l'output ICU si adattano all'impostazione regionale.

## Parametri [#parameters]

| Parametro             | Descrizione                                                                                         | Tipo     | Facoltativo | Predefinito |
| --------------------- | --------------------------------------------------------------------------------------------------- | -------- | ----------- | ----------- |
| [`message`](#message) | Il messaggio da formattare.                                                                         | `string` | No          | —           |
| [`options`](#options) | Configurazione di formattazione, comprese le impostazioni regionali di destinazione e le variabili. | `object` | Sì          | `{}`        |

### `message` [#message]

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

La stringa del messaggio da formattare. Può contenere pattern in formato ICU MessageFormat. Una stringa vuota restituisce una stringa vuota.

### `options` [#options]

**Tipo** `object` · **Facoltativo** · **Predefinito** `{}`

Configurazione della formattazione:

| Proprietà    | Descrizione                                                                                  | Tipo                             | Facoltativo | Predefinito |
| ------------ | -------------------------------------------------------------------------------------------- | -------------------------------- | ----------- | ----------- |
| `locales`    | Impostazioni regionali da usare per la formattazione.                                        | `string \| string[]`             | Sì          | `'en'`      |
| `variables`  | Oggetto contenente le variabili per l'interpolazione.                                    | `FormatVariables`                | Sì          | `{}`        |
| `dataFormat` | Il formato del messaggio. Quando è `'STRING'`, il messaggio viene restituito così com'è. | `'ICU' \| 'I18NEXT' \| 'STRING'` | Sì          | `'ICU'`     |

## Valore restituito [#returns]

**Tipo** `string`

Il messaggio formattato con le variabili sostituite e con la formattazione specifica dell'impostazione regionale applicata.

## Esempi [#examples]

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

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

```typescript
// Funzione di utilità per la formattazione senza istanziare la 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
// Formattazione di valuta e numeri

// Formattazione con impostazione regionale tedesca (la valuta richiede uno skeleton di valuta)
const germanPrice = formatMessage('Preis: {price, number, ::currency/EUR}', {
  locales: ['de'],
  variables: { price: 1234.56 },
});
console.log(germanPrice); // "Preis: 1.234,56 €"

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

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

// Template di messaggi riutilizzabili
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');
// Nota: formatMessage non traduce il testo — solo le regole ICU plural/format
// seguono l'impostazione regionale, quindi il testo letterale in inglese viene restituito invariato.
console.log(templates.welcome('Marie')); // "Welcome back, Marie!"
console.log(templates.itemCount(5)); // "5 items"
```

## Note [#notes]

* Richiede la specifica esplicita dell&#39;impostazione regionale nelle opzioni per le impostazioni regionali non predefinite; in caso contrario, usa `'en'` come fallback.
* Supporta le stesse funzionalità del formato ICU MessageFormat del metodo della classe GT.
* Restituisce una stringa vuota per i template di input vuoti.
* Le variabili vengono elaborate secondo le regole di formattazione ICU; se una variabile a cui si fa riferimento non viene fornita, viene generato un errore `MISSING_VALUE`.