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

title: formatMessage
description: Formatea mensajes con formato ICU sin una instancia de GT. Referencia de la API de formatMessage.

---

[`formatMessage`](/docs/platform/core/reference/gt-class-methods/formatting/format-message) es una función de utilidad independiente de la biblioteca Core de General Translation que formatea mensajes con sustitución de variables y formato según la configuración regional. Es compatible con patrones del formato de mensajes ICU, lo que la convierte en la herramienta principal para la interpolación de variables y la pluralización.

## Descripción general [#overview]

Importa `formatMessage` directamente desde `generaltranslation` y llámalo con una cadena de mensaje y un objeto de opciones. No requiere una clave de API ni una instancia de [GT](/docs/platform/core/reference/gt-class/constructor). Si quieres un formateo basado en instancias que herede la configuración regional de la instancia, usa en su lugar el método [`formatMessage`](/docs/platform/core/reference/gt-class-methods/formatting/format-message) de una instancia de [`GT`](/docs/platform/core/reference/gt-class/constructor).

Se basa en la biblioteca [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) de Format.JS, por lo que también admite el formateo de números y fechas, además de plurales y selecciones.

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

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

Firma:

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

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

* **Gestión de la configuración regional.** Usa las `locales` proporcionadas para aplicar el formato y recurre a `'en'` cuando no se especifica ninguna. Las listas actúan como una cadena de respaldo de configuración regional.
* **Procesamiento de variables.** Las variables se sustituyen en el mensaje. Los marcadores de posición simples `{variable}` se reemplazan por sus valores; el formato de mensajes ICU admite por completo plurales, selecciones y formato.
* **Formato de datos.** `dataFormat` usa `'ICU'` de forma predeterminada. Cuando se establece en `'STRING'`, el mensaje se devuelve tal cual, sin procesarlo como ICU.
* **Compatibilidad con el formato de mensajes.** Están disponibles las mismas funciones de ICU que en el método de la clase GT: formato de números (`{price, number, ::currency/USD}`), formato de fechas (`{date, date, short}`), pluralización (`{count, plural, ...}`) y selección (`{gender, select, ...}`).
* **Sin traducción.** Esta función da formato e interpola un mensaje; no traduce el texto del mensaje en sí. Solo los valores de las variables y el resultado de ICU se adaptan a la configuración regional.

## Parámetros [#parameters]

| Parámetro             | Descripción                                                                                    | Tipo     | Opcional | Predeterminado |
| --------------------- | ---------------------------------------------------------------------------------------------- | -------- | -------- | -------------- |
| [`message`](#message) | El mensaje que se va a formatear.                                                              | `string` | No       | —              |
| [`options`](#options) | Configuración de formato, incluidas las configuraciones regionales de destino y las variables. | `object` | Sí       | `{}`           |

### `message` [#message]

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

La cadena de mensaje que se va a formatear. Puede contener patrones del formato de mensajes ICU. Una cadena vacía devuelve una cadena vacía.

### `options` [#options]

**Tipo** `object` · **Opcional** · **Predeterminado** `{}`

Configuración de formato:

| Propiedad    | Descripción                                                                    | Tipo                             | Opcional | Predeterminado |
| ------------ | ------------------------------------------------------------------------------ | -------------------------------- | -------- | -------------- |
| `locales`    | Configuración regional que se usará para el formato.                           | `string \| string[]`             | Sí       | `'en'`         |
| `variables`  | Objeto que contiene variables para la interpolación.                           | `FormatVariables`                | Sí       | `{}`           |
| `dataFormat` | El formato del mensaje. Cuando es `'STRING'`, el mensaje se devuelve tal cual. | `'ICU' \| 'I18NEXT' \| 'STRING'` | Sí       | `'ICU'`        |

## Devuelve [#returns]

**Tipo** `string`

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

## Ejemplos [#examples]

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

// Uso básico
const greeting = formatMessage('Hello {name}!', {
  locales: ['en'],
  variables: { name: 'World' },
});
console.log(greeting); // "Hello World!"
```

```typescript
// Función utilitaria para formatear sin instanciar una clase
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
// Formato de moneda y números

// Formato para la configuración regional alemana (la moneda requiere un skeleton de moneda)
const germanPrice = formatMessage('Preis: {price, number, ::currency/EUR}', {
  locales: ['de'],
  variables: { price: 1234.56 },
});
console.log(germanPrice); // "Preis: 1.234,56 €"

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

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

// Plantillas de mensajes reutilizables
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 no traduce el texto — solo las reglas de plural/formato ICU
// siguen la configuración regional, por lo que el texto literal en inglés se devuelve tal cual.
console.log(templates.welcome('Marie')); // "Welcome back, Marie!"
console.log(templates.itemCount(5)); // "5 items"
```

## Notas [#notes]

* Requiere especificar explícitamente la configuración regional en las opciones para las configuraciones regionales no predeterminadas; de lo contrario, vuelve a `'en'`.
* Admite las mismas funciones del formato de mensajes ICU que el método de la clase GT.
* Devuelve una cadena vacía cuando las plantillas de entrada están vacías.
* Las variables se procesan de acuerdo con las reglas de formato de ICU; si no se proporciona una variable referenciada, se genera un error `MISSING_VALUE`.