Sintaxis del formato del mensaje

Vue I18n puede usar la sintaxis de formato de mensaje para localizar los mensajes que se mostrarán en la interfaz de usuario. Los mensajes de Vue I18n son interpolaciones y mensajes con varias sintaxis de características.

Interpolaciones

Vue I18n admite interpolación usando marcadores de posición {} como "Mustache".

Interpolación con nombre

La interpolación con nombre puede ser interpolada en el marcador de posición usando nombres de variables definidos en JavaScript.

Como ejemplo, el siguiente recurso de mensajes locales:

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

Los mensajes locales son el recurso especificado por la opción messages de createI18n. Se define el idioma en con { message: { hello: '{msg} world' } }.

La interpolación con nombre le permite especificar variables definidas en JavaScript. En el mensaje local anterior, puede localizarlo proporcionando la variable msg definida en JavaScript como un parámetro a la función de traducción.

El nombre de la variable dentro de {} debe comenzar con una letra (a-z, A-Z) o un guión bajo (_), seguido de cualquier combinación de letras, dígitos, guiones bajos (_), guiones (-) o signos de dólar ($).

Ejemplos: {msg}, {_userName}, {user-id}, {total$}

A continuación se muestra un ejemplo del uso de $t en una plantilla:

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

El primer argumento es message.hello como clave de mensajes locales, y el segundo argumento es un objeto con la propiedad msg como parámetro para $t.

TIP

La clave de recurso de mensaje local para la función de traducción puede ser especificada para un espacio de nombres de recurso específico usando . (punto), tal como un objeto de JavaScript.

TIP

$t tiene algunas sobrecargas. Sobre estas sobrecargas, vea la Referencia de API

Como resultado, el siguiente:

<p>hello world</p>

Interpolación de lista

La interpolación de lista puede ser interpolada en el marcador de posición usando una matriz definida en JavaScript.

Como ejemplo, el siguiente recurso de mensajes locales:

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

Se define el idioma en con { message: { hello: '{0} world' } }.

La interpolación de lista le permite especificar una matriz definida en JavaScript. En el mensaje local anterior, puede ser localizado proporcionando el elemento del índice 0 de la matriz definida por JavaScript como parámetro a la función de traducción.

A continuación se muestra un ejemplo del uso de $t en una plantilla:

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

El primer argumento es message.hello como clave de mensajes locales, y el segundo argumento es una matriz que contiene el ítem 'hello' como parámetro para $t.

Como resultado, el siguiente:

<p>hello world</p>

Interpolación literal

La interpolación literal puede ser interpolada en el marcador de posición usando una cadena literal.

Como ejemplo, el siguiente recurso de mensajes locales:

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

Se define el idioma en con { address: "{account}{'@'}{domain}" }.

La interpolación literal le permite especificar una cadena literal entre comillas simples '. El mensaje especificado con interpolación literal es localizado como una cadena por la función de traducción.

A continuación se muestra un ejemplo del uso de $t en una plantilla:

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

El primer argumento es address como clave de mensajes locales, y el segundo argumento es un objeto con las propiedades account y domain como parámetros para $t.

Como resultado, el siguiente:

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

NOTA

La interpolación literal es útil para caracteres especiales en la sintaxis de formato de mensaje, tales como { y }, que no pueden usarse directamente en el mensaje.

Mensajes vinculados

Si hay una clave de mensajes locales que siempre tendrá el mismo texto concreto que otra, simplemente puedes vincularla.

Para vincular a otra clave de mensajes locales, todo lo que tienes que hacer es prefijar su contenido con un signo @:key seguido del nombre completo de la clave de mensajes locales incluyendo el espacio de nombres al que quieres vincular.

Mensajes locales a continuación:

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

Es el idioma en que tiene una estructura jerárquica en el objeto.

El message.the_world tiene the world y message.dio. El message.linked tiene @:message.dio @:message.dio @:message.the_world !!!!, y está vinculado a la clave de mensajes locales con message.dio y message.the_world.

A continuación se muestra un ejemplo del uso de $t en una plantilla:

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

El primer argumento es message.linked como clave de mensajes locales como parámetro para $t.

Como resultado, el siguiente:

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

Modificadores integrados

Si el idioma distingue casos de caracteres, puede necesitar controlar el caso de los mensajes locales vinculados. Los mensajes vinculados pueden ser formateados con el modificador @.modifier:key

Los siguientes modificadores están disponibles actualmente integrados.

• upper: Poner todas las letras del mensaje vinculado en mayúsculas
• lower: Poner todas las letras del mensaje vinculado en minúsculas
• capitalize: Capitalizar la primera letra del mensaje vinculado

Mensajes locales a continuación:

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

Es el idioma en que tiene una estructura jerárquica en el objeto.

El message.homeAddress tiene Home address. El message.missingHomeAddress tiene Please provide @.lower:message.homeAddress, y está vinculado a la clave de mensajes locales con message.homeAddress.

Ya que el modificador .lower se especifica en el ejemplo anterior, así que la clave vinculada message.homeAddress se resuelve, después se evalúa.

A continuación se muestra un ejemplo del uso de $t en una plantilla:

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

Como resultado, el siguiente:

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

Modificadores personalizados

Si quieres usar modificadores no integrados, puedes usar tus modificadores personalizados.

Para usar modificadores personalizados, debes especificarlos en la opción modifiers de createI18n:

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

Mensajes locales a continuación:

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

Es el idioma en que tiene una estructura jerárquica en el objeto.

El message.snake tiene snake case. El message.custom_modifier tiene custom modifiers example: @.snakeCase:{'message.snake'}, y está vinculado a la clave de mensajes locales, que se interpola con literal.

NOTA

Puede usar las interpolaciones (con nombre, de lista y literal) para la clave de mensajes vinculados mostrados a continuación.

Este ejemplo muestra el uso de modificadores (@.lower, @.upper, @.capitalize) combinados con interpolaciones con nombre, de lista y literales.

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'
  }
}

Interpolación con nombre con modificador

En message.greeting, usamos una interpolación con nombre para {count} y vinculamos a message.name, aplicando el modificador .lower.

La clave message.name contiene {name}, que será interpolado con el parámetro name pasado.

El message.greeting está vinculado a la clave de mensaje local message.name.

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

Como resultado, el siguiente

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

Interpolación de lista con modificador

En este caso, los valores para {0} y {1} se pasan como una matriz. Las claves name y day se resuelven mediante interpolación de lista y se transforman con modificadores.

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

Como resultado, el siguiente

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

Interpolación literal con modificador

En este ejemplo, usamos una cadena literal dentro del mensaje y aplicamos el modificador .lower.

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

Aquí, el modificador se aplica al contenido dentro de domain, y el @ se preserva como salida literal.

Como resultado, el siguiente

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

Caracteres especiales

Los siguientes caracteres utilizados en la sintaxis de formato de mensaje son procesados por el compilador como caracteres especiales:

• {
• }
• @
• $
• |

Si quieres usar estos caracteres, necesitarás usar la Interpolación literal.

Formato Rails i18n

Vue I18n admite el formato de mensaje compatible con Ruby on Rails i18n.

Puedes interpolarte la sintaxis de formato de mensaje con % como prefijo:

IMPORTANTE

A partir de la versión 10, el formato Rails i18n será obsoleto. Recomendamos usar la interpolación con nombre.

Como ejemplo, el siguiente recurso de mensajes locales:

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

Se define el idioma en con { message: { hello: '%{msg} world' } }.

Al igual que en la Interpolación con nombre, puedes especificar variables definidas en JavaScript. En el mensaje local anterior, es posible localizarlo proporcionando una variable definida en JavaScript msg como parámetro a la función de traducción.

A continuación se muestra un ejemplo del uso de $t en una plantilla:

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

Como resultado, el siguiente:

<p>hello world</p>

Mensaje HTML

Puedes localizarlo con mensajes que contienen HTML.

PELIGRO

⚠️ Localizar dinámicamente HTML arbitrario en tu sitio puede ser muy peligroso porque puede conducir fácilmente a vulnerabilidades XSS. Solo usa interpolación HTML en contenido confiable y nunca en contenido proporcionado por el usuario.

Recomendamos usar la Interpolación de componentes.

AVISO

Si el mensaje contiene HTML, Vue I18n emite una advertencia a la consola en modo de desarrollo (process.env.NODE_ENV !== 'production'), Vue I18n emite una advertencia a la consola.

Puedes controlar la salida de advertencias con las opciones warnHtmlInMessage o warnHtmlMessage en createI18n o useI18n.

Como ejemplo, el siguiente recurso de mensajes locales:

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

Se define el idioma en con { message: { hello: 'hello <br> world' } }.

A continuación se muestra un ejemplo del uso de v-html y $t en una plantilla:

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

Como resultado, el siguiente:

<p>hello
<!--<br> existe pero se representa como html y no como una cadena-->
world</p>