vue-i18n locale files: JSON, YAML, pipe plurals, and {named} placeholders

Folder structure

The most common layout is a locales/ directory with one file per locale. Each file contains every translation key for that language:

my-vue-app/
├── src/
│   ├── i18n.ts          ← createI18n() setup
│   └── ...
├── locales/
│   ├── en.json          ← English (source)
│   ├── de.json          ← German
│   ├── fr.json          ← French
│   └── ja.json          ← Japanese
└── package.json

In your i18n.ts setup file, import each locale and pass it to createI18n():

import { createI18n } from 'vue-i18n'
import en from '../locales/en.json'
import de from '../locales/de.json'

const i18n = createI18n({
  locale: 'en',
  fallbackLocale: 'en',
  messages: { en, de },
})

export default i18n

Basic JSON format

Locale files can use flat keys or nested objects. vue-i18n resolves nested keys with dot notation:

{
  "hello": "Hello!",
  "nav": {
    "home": "Home",
    "about": "About us",
    "contact": "Contact"
  },
  "footer": {
    "copyright": "© 2026 My App"
  }
}

In a Vue template, use $t() to access any key:

<template>
  <h1>{{ $t('hello') }}</h1>
  <nav>
    <a href="/">{{ $t('nav.home') }}</a>
    <a href="/about">{{ $t('nav.about') }}</a>
  </nav>
  <footer>{{ $t('footer.copyright') }}</footer>
</template>

{named} placeholders

vue-i18n uses single curly braces for named placeholders — not double braces like some other libraries:

{
  "welcome": "Welcome, {name}!",
  "itemsInCart": "You have {count} items in your cart.",
  "orderConfirm": "Order #{orderId} confirmed for {email}."
}

Pass the values as the second argument to $t():

<template>
  <p>{{ $t('welcome', { name: 'Alice' }) }}</p>
  <!-- Output: "Welcome, Alice!" -->

  <p>{{ $t('itemsInCart', { count: 3 }) }}</p>
  <!-- Output: "You have 3 items in your cart." -->
</template>

Pipe-separated plurals

vue-i18n handles pluralization by splitting a single string on the pipe character |. The segments map to plural forms based on the count:

{
  "car": "car | cars",
  "apple": "no apples | one apple | {count} apples",
  "item": "no items | one item | {n} items"
}

How the segments are resolved:

• •Two segments ("car | cars"): first for count 1, second for everything else.
• •Three segments ("no apples | one apple | {count} apples"): first for 0, second for 1, third for 2+.

Use $t() with a count parameter or the legacy $tc() helper:

<template>
  <!-- Vue I18n v9+ (Composition API or Legacy) -->
  <p>{{ $t('apple', { count: 0 }) }}</p>
  <!-- Output: "no apples" -->

  <p>{{ $t('apple', { count: 1 }) }}</p>
  <!-- Output: "one apple" -->

  <p>{{ $t('apple', { count: 5 }) }}</p>
  <!-- Output: "5 apples" -->

  <!-- Legacy $tc() — still works but $t() with plural is preferred -->
  <p>{{ $tc('car', 2) }}</p>
  <!-- Output: "cars" -->
</template>

YAML support

vue-i18n supports YAML locale files alongside JSON. The structure is identical — only the syntax differs. YAML is popular for its readability and lack of trailing-comma issues:

# locales/en.yaml
hello: Hello!
nav:
  home: Home
  about: About us
  contact: Contact
welcome: "Welcome, {name}!"
car: car | cars
apple: "no apples | one apple | {count} apples"

To use YAML, install @intlify/unplugin-vue-i18n (or the Vite/Webpack plugin) which handles YAML parsing at build time. Nuxt’s @nuxtjs/i18n supports YAML out of the box.

Linked locale messages

The @:key syntax lets one message reference another, reducing duplication:

{
  "the_world": "the world",
  "dio": "DIO",
  "greeting": "hello, @:the_world!",
  "villainGreeting": "@:dio says @:greeting"
}

$t('greeting') resolves to "hello, the world!". You can also apply modifiers to change the case of linked text:

{
  "homeAddress": "Home address",
  "missing498": "Please provide @.lower:homeAddress",
  "heading": "@.upper:homeAddress",
  "label": "@.capitalize:homeAddress"
}

• •@.upper:key — converts the linked value to uppercase.
• •@.lower:key — converts the linked value to lowercase.
• •@.capitalize:key — capitalizes the first letter.

SFC <i18n> blocks

Vue Single File Components can embed translations directly using a custom <i18n> block. This keeps component-specific translations co-located with the component:

<template>
  <h1>{{ $t('title') }}</h1>
  <p>{{ $t('description') }}</p>
</template>

<script setup>
// component logic
</script>

<i18n>
{
  "en": {
    "title": "My Component",
    "description": "This component does something useful."
  },
  "de": {
    "title": "Meine Komponente",
    "description": "Diese Komponente macht etwas Nützliches."
  }
}
</i18n>

The <i18n> block also supports YAML by adding lang="yaml":

<i18n lang="yaml">
en:
  title: My Component
  description: This component does something useful.
de:
  title: Meine Komponente
  description: Diese Komponente macht etwas Nützliches.
</i18n>

Common mistakes

vue-i18n format at a glance

Related guides