Простые сообщения и плейсхолдеры

В основе работы FormatJS лежит ICU MessageFormat — универсальный формат описания локализуемых строк. Простые сообщения представляют собой базовый уровень этой системы: строка текста с возможными подстановками значений.

Минимальное сообщение не содержит параметров и выглядит как обычная строка:

const message = "Hello world";

При использовании IntlMessageFormat строка интерпретируется как сообщение без переменных и возвращается без изменений.

import { IntlMessageFormat } from 'intl-messageformat';

const msg = new IntlMessageFormat("Hello world", "en");
console.log(msg.format());

Результат:

Hello world

Такая форма используется как базовый случай, когда локализация требуется только для хранения текстов без динамических частей.

Плейсхолдеры как основа динамических сообщений

Плейсхолдеры позволяют внедрять динамические данные внутрь строк. В ICU-синтаксисе они обозначаются фигурными скобками {}.

Базовая структура:

"Hello {name}"

Пример использования:

const msg = new IntlMessageFormat("Hello {name}", "en");

console.log(msg.format({
  name: "Alice"
}));

Результат:

Hello Alice

Плейсхолдеры работают как именованные переменные. Каждое имя внутри {} должно соответствовать ключу объекта, передаваемого в format().

Множественные плейсхолдеры

Сообщения могут содержать несколько переменных одновременно. ICU-синтаксис позволяет комбинировать их в одной строке без ограничений по количеству.

const msg = new IntlMessageFormat(
  "{greeting}, {name}! You have {count} new messages.",
  "en"
);

console.log(msg.format({
  greeting: "Hello",
  name: "Alice",
  count: 5
}));

Результат:

Hello, Alice! You have 5 new messages.

Каждый плейсхолдер независимо связывается с соответствующим ключом объекта данных. Порядок ключей в объекте не имеет значения.

Встраивание плейсхолдеров в сложные строки

Плейсхолдеры могут находиться в любом месте строки: в начале, середине или конце предложения. ICU не накладывает ограничений на их расположение.

const msg = new IntlMessageFormat(
  "{user} joined the room at {time}",
  "en"
);

console.log(msg.format({
  user: "Bob",
  time: "10:45"
}));

Результат:

Bob joined the room at 10:45

Такой подход позволяет строить гибкие шаблоны сообщений, которые сохраняют естественный порядок слов для разных языков.

Типы значений в плейсхолдерах

Плейсхолдеры не ограничены строками. В них могут передаваться числа, даты и булевы значения. Библиотека приводит их к строковому представлению с учётом локали.

const msg = new IntlMessageFormat(
  "Balance: {balance}",
  "en"
);

console.log(msg.format({
  balance: 1250
}));

Результат:

Balance: 1250

Числа интерпретируются напрямую, но при необходимости форматирование может быть расширено через дополнительные ICU-правила.

Поведение при отсутствии значений

Если плейсхолдер не получает значение, результат зависит от режима обработки. В базовом случае возвращается строковое представление undefined.

const msg = new IntlMessageFormat("Hello {name}", "en");

console.log(msg.format({}));

Результат:

Hello {name}

Такое поведение подчёркивает необходимость явного предоставления всех требуемых переменных. В прикладных системах обычно обеспечивается предварительная валидация данных перед форматированием.

Экранирование фигурных скобок

Так как {} используются для обозначения плейсхолдеров, для вывода их как текста применяется экранирование с помощью одинарных кавычек.

ICU-правило:

'{'
'}'

Пример:

const msg = new IntlMessageFormat(
  "Set value to '{value}'",
  "en"
);

console.log(msg.format());

Результат:

Set value to {value}

Без экранирования система попыталась бы интерпретировать value как переменную.

Использование плейсхолдеров в реальных интерфейсах

Плейсхолдеры часто применяются в пользовательских интерфейсах: уведомлениях, статусах, системных сообщениях. Их основная задача — отделение текста от данных.

Пример сообщения для уведомлений:

const msg = new IntlMessageFormat(
  "{count} items deleted",
  "en"
);

console.log(msg.format({
  count: 3
}));

Результат:

3 items deleted

Такой подход позволяет повторно использовать одну строку для различных значений без изменения структуры сообщения.

Вложенные конструкции с простыми сообщениями

Даже в рамках простых сообщений допускается вложение нескольких плейсхолдеров в одной логической части строки.

const msg = new IntlMessageFormat(
  "{firstName} {lastName} ({username})",
  "en"
);

console.log(msg.format({
  firstName: "John",
  lastName: "Doe",
  username: "jdoe"
}));

Результат:

John Doe (jdoe)

Такие конструкции часто используются для отображения пользовательских профилей и идентификаторов.

Согласованность ключей и структура данных

Ключи плейсхолдеров формируют контракт между текстом и данными. ICU-сообщение становится зависимым от структуры объекта, передаваемого в format().

Пример:

const msg = new IntlMessageFormat(
  "Project {project} has status {status}",
  "en"
);

Ожидаемая структура данных:

{
  project: string,
  status: string
}

Несоответствие ключей приводит к отсутствию подстановки, что нарушает целостность сообщения.

Простые сообщения как базовый слой интернационализации

Простые сообщения формируют фундамент всей системы форматирования. Они используются как базовый уровень, на который накладываются более сложные конструкции ICU: множественное число, выбор форм, форматирование дат и чисел.

Даже при наличии расширенных возможностей система всегда поддерживает обратную совместимость с простыми строками и плейсхолдерами, что делает их универсальным инструментом описания текста в интернационализированных приложениях.

Оглавление