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

title: formatMessage
description: Da formato a mensajes con formato ICU con variables y valores adaptados a la configuración regional. Referencia de la API de formatMessage.

---

Da formato a un mensaje con sustitución de variables y formato adaptado a la configuración regional en una instancia de [GT](/docs/platform/core/reference/gt-class/constructor). General Translation se basa en la biblioteca [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) de Format.JS para admitir patrones del formato de mensajes ICU, incluida la interpolación de variables, la pluralización, el formato de números y el de fechas.

## Descripción general [#overview]

Llama a `formatMessage` sobre una instancia de [`GT`](/docs/platform/core/reference/gt-class/constructor) con una cadena de mensaje y un objeto de opciones opcional que contiene las `variables` que se van a interpolar. Devuelve el mensaje formateado.

```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` se ejecuta localmente con `IntlMessageFormat` (de `intl-messageformat`) y no requiere una clave de API. Anula la lista de configuraciones regionales de la instancia cuando se proporciona `locales`. Para formatear sin una instancia de `GT`, consulta la versión independiente de [`formatMessage`](/docs/platform/core/reference/utility-functions/formatting/format-message).*

## Cómo funciona [#how-it-works]

* **Procesamiento de ICU.** El método analiza la sintaxis del formato de mensajes ICU con `IntlMessageFormat` (de `intl-messageformat`) y aplica automáticamente el formato de números, fechas y monedas según la configuración regional.
* **Resolución de configuraciones regionales.** `locales` reemplaza los valores predeterminados de la instancia en una sola llamada.
* **Las variables faltantes provocan un error.** Si se hace referencia en el mensaje a una variable que no se proporciona en `variables`, se produce un error.
* **Escape de llaves.** Siguiendo la sintaxis de ICU, encierra una llave literal entre comillas simples (`'{'` o `'}'`) para que no se interprete como el inicio de un marcador de posición.

### Sustitución de variables

* Variables simples: `{variableName}` se sustituye por el valor de la cadena.
* Patrones de ICU: `{count, plural, ...}` se procesan según las reglas de formato de ICU.
* Variables faltantes: generan un error.
* Llaves literales: enciérralas entre comillas simples siguiendo la sintaxis de ICU (`'{'` o `'}'`) para mostrar una llave literal.

### Compatibilidad con el formato de mensajes

* **Interpolación simple:** `{variable}`
* **Formato de números:** `{price, number, ::currency/USD}`, `{discount, number, percent}`, `{num, number, integer}`
* **Formato de fecha:** `{date, date, short}`, `{time, time, short}`
* **Pluralización:** `{count, plural, =0 {none} =1 {one} other {many}}`
* **Selección:** `{gender, select, male {he} female {she} other {they}}`
* **Selectordinal:** `{place, selectordinal, =1 {#st} =2 {#nd} =3 {#rd} other {#th}}`

## Parámetros [#parameters]

| Parámetro             | Descripción                                        | Type     | Opcional | Predeterminado |
| --------------------- | -------------------------------------------------- | -------- | -------- | -------------- |
| [`message`](#message) | El mensaje con formato ICU que se debe formatear.  | `string` | No       | —              |
| [`options`](#options) | Configuración de formato, incluidas las variables. | `object` | Sí       | —              |

### `message` [#message]

**Tipo** `string` · **Obligatorio**

El mensaje que se debe formatear con la sintaxis del formato de mensajes ICU.

### `options` [#options]

**Tipo** `object` · **Opcional**

Configuración de formato:

| Nombre       | Descripción                                                                                                    | Tipo                 | Opcional | Predeterminado          |
| ------------ | -------------------------------------------------------------------------------------------------------------- | -------------------- | -------- | ----------------------- |
| `locales`    | Configuraciones regionales que se usarán para el formato (anulan los valores predeterminados de la instancia). | `string \| string[]` | Sí       | locales de la instancia |
| `variables`  | Objeto de variables para la interpolación de mensajes.                                                         | `FormatVariables`    | Sí       | `{}`                    |
| `dataFormat` | Formato de datos de la cadena de mensaje (`'ICU'`, `'I18NEXT'` o `'STRING'`).                                  | `StringFormat`       | Sí       | `'ICU'`                 |

El tipo `FormatVariables`:

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

## Returns [#returns]

**Type** `string`

El mensaje con formato, con las variables sustituidas y el formato específico de la configuración regional aplicado.

## Ejemplos [#examples]

```typescript
// Sustitución básica de variables
const gt = new GT({ targetLocale: 'en' });

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

```typescript
// Pluralización 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
// Formato de números y monedas
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
// Plantillas de mensajes complejos
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'),
  },
});
```

## Notas [#notes]

* El método procesa la sintaxis del formato de mensajes ICU con `IntlMessageFormat` (de `intl-messageformat`).
* Si faltan variables, se produce un error.
* El formato de números, fechas y monedas según la configuración regional se aplica automáticamente.
* Para dar formato a números independientes, usa [`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num).