消息格式语法

Vue I18n 可以使用消息格式语法来本地化要在 UI 中显示的消息。Vue I18n 消息是插值和带有各种特性语法的消息。

插值

Vue I18n 支持使用占位符 {} 的插值，就像"Mustache"一样。

命名插值

命名插值可以在占位符中使用在 JavaScript 中定义的变量名进行插值。

例如，以下语言环境消息资源：

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

语言环境消息是通过 createI18n 的 messages 选项指定的资源。它定义了 en 语言环境，其中包含 { message: { hello: '{msg} world' } }。

命名插值允许您指定在 JavaScript 中定义的变量。在上面的语言环境消息中，您可以通过将 JavaScript 定义的 msg 作为参数传递给翻译函数来本地化它。

花括号 {} 中的变量名必须以字母（a-z, A-Z）或下划线（_）开头，后面可以跟任何字母、数字、下划线（_）、连字符（-）或美元符号（$）的组合。

示例：{msg}、{_userName}、{user-id}、{total$}

以下是在模板中使用 $t 的示例：

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

第一个参数是语言环境消息键 message.hello，第二个参数是带有 msg 属性的对象作为 $t 的参数。

TIP

翻译函数的语言环境消息资源键可以通过使用 .（点）指定特定资源命名空间，就像 JavaScript 对象一样。

TIP

$t 有一些重载。关于这些重载，请参见 API 参考

结果如下：

<p>hello world</p>

列表插值

列表插值可以在占位符中使用在 JavaScript 中定义的数组进行插值。

例如，以下语言环境消息资源：

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

它定义了 en 语言环境，其中包含 { message: { hello: '{0} world' } }。

列表插值允许您指定在 JavaScript 中定义的数组。在上面的语言环境消息中，您可以通过将 JavaScript 定义的数组的第 0 个索引项作为参数传递给翻译函数来进行本地化。

以下是在模板中使用 $t 的示例：

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

第一个参数是语言环境消息键 message.hello，第二个参数是包含 'hello' 项目的数组作为 $t 的参数。

结果如下：

<p>hello world</p>

字面量插值

字面量插值可以在占位符中使用字面量字符串进行插值。

例如，以下语言环境消息资源：

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

它定义了 en 语言环境，其中包含 { address: "{account}{'@'}{domain}" }。

字面量插值允许您指定用单引号 ’ 引起来的字符串字面量。使用字面量插值指定的消息通过翻译函数被作为字符串进行本地化。

以下是在模板中使用 $t 的示例：

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

第一个参数是语言环境消息键 address，第二个参数是带有 account 和 domain 属性的对象作为 $t 的参数。

结果如下：

<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 的示例：

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

第一个参数是作为 $t 参数的语言环境消息键 message.linked。

结果如下：

<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 的示例：

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

结果如下：

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

自定义修饰符

如果您想使用非内置修饰符，可以使用自定义修饰符。

要使用自定义修饰符，您必须在 createI18n 的 modifiers 选项中指定它们：

const i18n = createI18n({
  locale: 'en',
  messages: {
    // 设置一些语言环境消息...
  },
  // 在 `modifiers` 选项中设置自定义修饰符
  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。

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

结果如下：

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

带修饰符的列表插值

在这种情况下，{0} 和 {1} 的值作为数组传递。键 name 和 day 使用列表插值解析并应用修饰符。

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

结果如下：

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

带修饰符的字面量插值

在这个示例中，我们在消息中使用字面量字符串并应用 .lower 修饰符。

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

在这里，修饰符应用于 domain 内的内容，并且 @ 作为字面量输出保留。

结果如下：

<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 的示例：

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

结果如下：

<p>hello world</p>

HTML 消息

您可以使用包含 HTML 的消息进行本地化。

危险

⚠️ 在您的站点上动态本地化任意 HTML 可能非常危险，因为它容易导致 XSS 漏洞。只对受信任的内容使用 HTML 插值，永远不要对用户提供的内容使用。

我们推荐使用 组件插值。

注意

如果消息包含 HTML，Vue I18n 在开发模式下（process.env.NODE_ENV !== 'production'）会在控制台输出警告，Vue I18n 会输出警告。

您可以通过在 createI18n 或 useI18n 中的 warnHtmlInMessage 或 warnHtmlMessage 选项控制警告输出。

例如，以下语言环境消息资源：

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

它定义了 en 语言环境，其中包含 { message: { hello: 'hello <br> world' } }。

以下是在模板中使用 v-html 和 $t 的示例：

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

结果如下：

<p>hello
<!--<br> 存在但被渲染为 HTML 而不是字符串-->
world</p>