Синтаксис форматирования сообщений

Vue I18n может использовать синтаксис форматирования сообщений для локализации сообщений, отображаемых в интерфейсе. Сообщения Vue I18n представляют собой интерполяции и сообщения с различными синтаксическими конструкциями.

Интерполяции

Vue I18n поддерживает интерполяцию с использованием заполнителей {} как в "Mustache".

Именованная интерполяция

Именованная интерполяция может быть выполнена в заполнителе с использованием имен переменных, определенных в JavaScript.

В качестве примера, следующий ресурс локализованных сообщений:

const messages = {
  en: {
    message: {
      hello: '{msg} world'
    }
  }
}

Ресурс локализованных сообщений - это ресурс, указанный с помощью опции messages функции createI18n. Определен локаль en с { message: { hello: '{msg} world' } }.

Именованная интерполяция позволяет указать переменные, определенные в JavaScript. В приведенном выше локализованном сообщении вы можете выполнить его локализацию, передав определенную в JavaScript переменную msg в качестве параметра функции перевода.

Имя переменной внутри {} должно начинаться с буквы (a-z, A-Z) или символа подчеркивания (_), за которым могут следовать любые комбинации букв, цифр, символов подчеркивания (_), дефисов (-) или знаков доллара ($).

Примеры: {msg}, {_userName}, {user-id}, {total$}

Ниже приведен пример использования $t в шаблоне:

html

<p>{{ $t('message.hello', { msg: 'hello' }) }}</p>

Первый аргумент - message.hello как ключ локализованного сообщения, второй аргумент - объект с свойством msg в качестве параметра для $t.

TIP

Ключ ресурса локализованного сообщения для функции перевода можно указать для конкретного пространства имен ресурсов с использованием . (точка), как в JavaScript объектах.

TIP

У $t есть несколько перегрузок. О перегрузках см. Справочник API

Результат ниже:

html

<p>hello world</p>

Интерполяция списков

Интерполяция списков может быть выполнена в заполнителе с использованием массива, определенного в JavaScript.

В качестве примера, следующий ресурс локализованных сообщений:

const messages = {
  en: {
    message: {
      hello: '{0} world'
    }
  }
}

Определена локаль en с { message: { hello: '{0} world' } }.

Интерполяция списков позволяет указать массив, определенный в JavaScript. В приведенном выше локализованном сообщении вы можете выполнить его локализацию, передав элемент с индексом 0 массива, определенного в JavaScript, в качестве параметра функции перевода.

Ниже приведен пример использования $t в шаблоне:

html

<p>{{ $t('message.hello', ['hello']) }}</p>

Первый аргумент - message.hello как ключ локализованного сообщения, второй аргумент - массив, содержащий элемент 'hello' в качестве параметра для $t.

Результат ниже:

html

<p>hello world</p>

Литеральная интерполяция

Литеральная интерполяция может быть выполнена в заполнителе с использованием строкового литерала.

В качестве примера, следующий ресурс локализованных сообщений:

const messages = {
  en: {
    address: "{account}{'@'}{domain}"
  }
}

Определена локаль en с { address: "{account}{'@'}{domain}" }.

Литеральная интерполяция позволяет указать строковый литерал, заключенный в одинарные кавычки '. Сообщение, указанное с литеральной интерполяцией, локализуется как строка функцией перевода.

Ниже приведен пример использования $t в шаблоне:

html

<p>email: {{ $t('address', { account: 'foo', domain: 'domain.com' }) }}</p>

Первый аргумент - address как ключ локализованного сообщения, второй аргумент - объект с свойствами account и domain в качестве параметра для $t.

Результат ниже:

html

<p>email: [email protected]</p>

ПРИМЕЧАНИЕ

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

Связанные сообщения

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

Чтобы связать другой ключ локализованного сообщения, вам нужно просто добавить префикс @:key к его содержанию, за которым следует полное имя ключа локализованного сообщения, включая пространство имен, к которому вы хотите выполнить связывание.

Локализованные сообщения ниже:

const messages = {
  en: {
    message: {
      the_world: 'the world',
      dio: 'DIO:',
      linked: '@:message.dio @:message.the_world !!!!'
    }
  }
}

Определена локаль en, которая имеет иерархическую структуру в объекте.

message.the_world содержит the world, а message.dio содержит DIO:. message.linked содержит @:message.dio @:message.dio @:message.the_world !!!!, и оно связано с ключами локализованных сообщений message.dio и message.the_world.

Ниже приведен пример использования $t в шаблоне:

html

<p>{{ $t('message.linked') }}</p>

Первый аргумент - message.linked как ключ локализованного сообщения в качестве параметра для $t.

Результат ниже:

html

<p>DIO: the world !!!!</p>

Встроенные модификаторы

Если язык отличает регистр символов, вам может понадобиться управлять регистром связанных локализованных сообщений. Связанные сообщения можно форматировать с модификатором @.modifier:key

Следующие модификаторы доступны встроенно.

upper: Привести все символы в связанном сообщении к верхнему регистру
lower: Привести все символы в связанном сообщении к нижнему регистру
capitalize: Заглавная первая буква в связанном сообщении

Локализованные сообщения ниже:

const messages = {
  en: {
    message: {
      homeAddress: 'Home address',
      missingHomeAddress: 'Please provide @.lower:message.homeAddress'
    }
  }
}

Определена локаль en, которая имеет иерархическую структуру в объекте.

message.homeAddress содержит Home address. message.missingHomeAddress содержит Please provide @.lower:message.homeAddress, и оно связано с ключом локализованного сообщения message.homeAddress.

Поскольку в приведенном выше примере указан модификатор .lower, то связанный ключ message.homeAddress разрешается, после чего выполняется его вычисление.

Ниже приведен пример использования $t в шаблоне:

html

<label>{{ $t('message.homeAddress') }}</label>
<p class="error">{{ $t('message.missingHomeAddress') }}</p>

Результат ниже:

html

<label>Home address</label>
<p class="error">Please provide home address</p>

Пользовательские модификаторы

Если вы хотите использовать не встроенные модификаторы, вы можете использовать свои собственные модификаторы.

Чтобы использовать пользовательские модификаторы, необходимо указать их в опции modifiers функции createI18n:

const i18n = createI18n({
  locale: 'en',
  messages: {
    // set something locale messages ...
  },
  // set custom modifiers at `modifiers` option
  modifiers: {
    snakeCase: (str) => str.split(' ').join('_')
  }
})

Локализованные сообщения ниже:

const messages = {
  en: {
    message: {
      snake: 'snake case',
      custom_modifier: "custom modifiers example: @.snakeCase:{'message.snake'}"
    }
  }
}

Определена локаль en, которая имеет иерархическую структуру в объекте.

message.snake содержит snake case. message.custom_modifier содержит custom modifiers example: @.snakeCase:{'message.snake'}, и оно связано с ключом локализованного сообщения, которое интерполируется с литералом.

ПРИМЕЧАНИЕ

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

Этот пример демонстрирует использование модификаторов (@.lower, @.upper, @.capitalize) в сочетании с именованной, списковой и литеральной интерполяцией.

const messages = {
  en: {
    message: {
      greeting: "Hello, @.lower:{'message.name'}! You have {count} new messages.",
      name:"{name}"
    },

    welcome: "Welcome, @.upper:{'name'}! Today is @.capitalize:{'day'}.",
    name: '{0}',
    day: '{1}',

    literalMessage: "This is an email: foo{'@'}@.lower:domain",
    domain: 'SHOUTING'
  }
}

Именованная интерполяция с модификатором

В message.greeting мы используем именованную интерполяцию для {count} и связываемся с message.name, применяя модификатор .lower.

Ключ message.name содержит {name}, который будет интерполирован с переданным параметром name.

message.greeting связан с ключом локализованного сообщения message.name.

html

<p>{{ $t('message.greeting', { name: 'Alice', count: 5 }) }}</p>

Результат ниже

html

<p>Hello, alice! You have 5 new messages.</p>

Списковая интерполяция с модификатором

В этом случае значения для {0} и {1} передаются в виде массива. Ключи name и day разрешаются с использованием списковой интерполяции и преобразуются с модификаторами.

html

<p>{{ $t('welcome', ['bob', 'MONDAY']) }}</p>

Результат ниже

html

<p>Welcome, BOB! Today is Monday.</p>

Литеральная интерполяция с модификатором

В этом примере мы используем строковый литерал внутри сообщения и применяем модификатор .lower.

html

<p>{{ $t('literalMessage') }}</p>

Здесь модификатор применяется к содержимому внутри domain, а символ @ сохраняется как строковый вывод.

Результат ниже

html

<p>This is an email: foo@shouting</p>

Специальные символы

Следующие символы, используемые в синтаксисе форматирования сообщений, обрабатываются компилятором как специальные символы:

Если вы хотите использовать эти символы, вам нужно использовать Литеральную интерполяцию.

Формат Rails i18n

Vue I18n поддерживает формат сообщений, совместимый с Ruby on Rails i18n.

Вы можете использовать синтаксис форматирования сообщений с префиксом %:

ВАЖНО

Начиная с версии v10 и далее, формат Rails i18n будет устаревшим. Рекомендуется использовать именованную интерполяцию.

В качестве примера, следующий ресурс локализованных сообщений:

const messages = {
  en: {
    message: {
      hello: '%{msg} world'
    }
  }
}

Определена локаль en с { message: { hello: '%{msg} world' } }.

Как и в случае с Именованной интерполяцией, вы можете указать переменные, определенные в JavaScript. В приведенном выше локализованном сообщении возможно выполнить его локализацию, передав определенную в JavaScript переменную msg в качестве параметра функции перевода.

Ниже приведен пример использования $t в шаблоне:

html

<p>{{ $t('message.hello', { msg: 'hello' }) }}</p>

Результат ниже:

html

<p>hello world</p>

HTML сообщения

Вы можете выполнить локализацию с сообщениями, содержащими HTML.

ОПАСНО

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

Рекомендуем использовать Интерполяцию компонентов.

УВЕДОМЛЕНИЕ

Если сообщение содержит HTML, Vue I18n выводит предупреждение в консоль при режиме разработки (process.env.NODE_ENV !== 'production'), Vue I18n выводит предупреждение в консоль.

Вы можете контролировать вывод предупреждений с помощью опций warnHtmlInMessage или warnHtmlMessage в createI18n или useI18n.

В качестве примера, следующий ресурс локализованных сообщений:

const messages = {
  en: {
    message: {
      hello: 'hello <br> world'
    }
  }
}

Определена локаль en с { message: { hello: 'hello <br> world' } }.

Ниже приведен пример использования v-html и $t в шаблоне:

html

<p v-html="$t('message.hello')"></p>

Результат ниже:

html

<p>hello
<!--<br> существует, но отображается как html, а не как строка-->
world</p>

general

Variables

Functions

Interfaces

Type Aliases

vue

Interfaces

Синтаксис форматирования сообщений

Интерполяции

Именованная интерполяция

Интерполяция списков

Литеральная интерполяция

Связанные сообщения

Встроенные модификаторы

Пользовательские модификаторы

Именованная интерполяция с модификатором

Списковая интерполяция с модификатором

Литеральная интерполяция с модификатором

Специальные символы

Формат Rails i18n

HTML сообщения

Синтаксис форматирования сообщений ​

Интерполяции ​

Именованная интерполяция ​

Интерполяция списков ​

Литеральная интерполяция ​

Связанные сообщения ​

Встроенные модификаторы ​

Пользовательские модификаторы ​

Именованная интерполяция с модификатором ​

Списковая интерполяция с модификатором ​

Литеральная интерполяция с модификатором ​

Специальные символы ​

Формат Rails i18n ​

HTML сообщения ​

Синтаксис форматирования сообщений

Интерполяции

Именованная интерполяция

Интерполяция списков

Литеральная интерполяция

Связанные сообщения

Встроенные модификаторы

Пользовательские модификаторы

Именованная интерполяция с модификатором

Списковая интерполяция с модификатором

Литеральная интерполяция с модификатором

Специальные символы

Формат Rails i18n

HTML сообщения