Skip to content
Tutorials Center
My learning

Topics

Lesson 70 of 87 ยท Performance, Security and Ecosystem

Internationalization with vue-i18n

Translate a Vue 3 app with vue-i18n: messages, locale switching, interpolation, pluralization, number and date formats, lazy-loaded locales and right-to-left support, with a runnable model.

If your audience speaks more than one language, hard-coded text becomes a problem. Internationalization (shortened to i18n: an "i", 18 letters, an "n") is the work of making an app able to be translated; localization (l10n) is the translating itself. In the Vue world the standard tool is vue-i18n, the official-style library for Vue 3.

Translating well is more than replacing words. Languages differ in plural rules (Polish and Arabic have more than two), in how numbers, dates and currencies are written, and in text direction (Arabic and Hebrew run right to left). This lesson shows the vue-i18n setup, then builds a runnable model of its core ideas on top of the browser's own Intl APIs, so you can see what each piece does.

Setting up vue-i18n

Install the package (npm install vue-i18n) and create the instance in its own module. Use legacy: false to get the Composition API mode, which is the right choice for new Vue 3 code. These files are read-only here, since the runner has no npm packages:

JavaScript
// src/i18n.js
import { createI18n } from "vue-i18n";

export const i18n = createI18n({
  legacy: false,                 // Composition API mode
  locale: "en",                  // the active language
  fallbackLocale: "en",          // used when a key is missing in the active language
  messages: {
    en: { greeting: "Hello, {name}!", nav: { home: "Home" } },
    de: { greeting: "Hallo, {name}!", nav: { home: "Startseite" } },
  },
});
JavaScript
// src/main.js
import { createApp } from "vue";
import App from "./App.vue";
import { i18n } from "./i18n";

createApp(App).use(i18n).mount("#app");

In a template, $t translates a key. In <script setup>, call useI18n():

VUE
<script setup>
import { useI18n } from "vue-i18n";

const { t, locale } = useI18n();
const title = t("nav.home");               // "Home" or "Startseite"
</script>

<template>
  <h1>{{ $t("greeting", { name: "Ada" }) }}</h1>   <!-- named interpolation -->
  <button @click="locale = locale === 'en' ? 'de' : 'en'">{{ locale }}</button>
</template>

Key points: keys are dotted paths into nested objects (nav.home); placeholders are filled from the object you pass; and locale is a ref, so changing it re-renders every translated string in the app.

Pluralization

English has two forms ("1 apple", "2 apples"), but many messages need a zero case too. vue-i18n uses the pipe character to separate the forms, and you pass the count as the second argument:

JavaScript
messages: {
  en: { apples: "no apples | one apple | {count} apples" },
  ru: { apples: "{n} ัะฑะปะพะบะพ | {n} ัะฑะปะพะบะฐ | {n} ัะฑะปะพะบ" },   // 3 forms for Russian
}
JavaScript
t("apples", 0);   // "no apples"
t("apples", 1);   // "one apple"
t("apples", 7);   // "7 apples"   ({count} and {n} are filled in automatically)

The number of forms and the rule that picks one depend on the language; vue-i18n lets you supply a pluralRules function per locale for the complicated ones. The browser knows these rules too: new Intl.PluralRules("ru").select(21) returns "one", select(22) returns "few". The runnable model below uses exactly that.

A tiny i18n model: interpolation, plurals and switching

Switch languages and the whole box re-translates, because t reads the locale ref while rendering, so Vue tracks it as a dependency. Click + in Polish to see 1 jabล‚ko, 2 jabล‚ka, 5 jabล‚ek, 22 jabล‚ka: the rules come from Intl.PluralRules, not from code in the app. Unknown keys show the key itself (nav.settings), which makes missing translations easy to spot.

Number and date formats

Never format numbers and dates by hand. 1,234.5 in English is 1.234,5 in German and 1 234,5 in French. vue-i18n lets you name formats once and apply them with n() and d(), which are built on Intl.NumberFormat and Intl.DateTimeFormat:

JavaScript
createI18n({
  legacy: false,
  locale: "en-US",
  numberFormats: {
    "en-US": { currency: { style: "currency", currency: "USD" } },
    "de-DE": { currency: { style: "currency", currency: "EUR" } },
  },
  datetimeFormats: {
    "en-US": { short: { dateStyle: "medium" } },
    "de-DE": { short: { dateStyle: "medium" } },
  },
});
VUE
<p>{{ $n(1234.5, "currency") }}</p>      <!-- $1,234.50 or 1.234,50 โ‚ฌ -->
<p>{{ $d(new Date(), "short") }}</p>     <!-- Nov 10, 2026 or 10.11.2026 -->

Note that the currency is part of your product decision, not of the language: a German-speaking customer in Switzerland still pays in CHF. Keep the money amount and its currency together in your data and let the locale only decide how it is written.

Lazy-loaded locales

If you ship every language in the main bundle, every visitor downloads text they will never read. Instead, bundle only the default locale and load the others on demand with a dynamic import(), then register them with setLocaleMessage:

JavaScript
// src/i18n.js
const loaded = new Set(["en"]);

export async function setLocale(locale) {
  if (!loaded.has(locale)) {
    const messages = await import(`./locales/${locale}.json`);   // a separate chunk per language
    i18n.global.setLocaleMessage(locale, messages.default);
    loaded.add(locale);
  }
  i18n.global.locale.value = locale;
  document.documentElement.lang = locale;
}

Call setLocale from a language picker, and also from a router guard if the locale is part of the URL (/de/products). Remember the choice (in localStorage or a cookie) and, on first visit, start from navigator.language.

The example below imitates this: a fake loader with a delay stands in for the dynamic import(), the page shows a loading state, and the language switch also updates lang and dir for right-to-left text.

Lazy-loaded locales, Intl formats and RTL

Pick German: the loading line appears for half a second, the file is "loaded on demand", and the price becomes 1.234,50 โ‚ฌ with a German date. Pick Arabic and the box switches direction (dir="rtl") while the number and date follow the Arabic locale. Switching back to a language you have already loaded is instant, because the loaded set remembers it.

Good habits for translatable apps

  • Never build sentences by concatenation. "Hello " + name + ", you have " + n + " messages" cannot be translated, because other languages reorder the words. Use one message with placeholders.
  • Do not hard-code text in components, including alt, title and aria-label. Screen reader labels need translating too (accessibility).
  • Use stable, descriptive keys such as cart.empty instead of the English sentence, so changing the wording does not break the key.
  • Leave room. German and Finnish words are long, so avoid fixed-width buttons; logical CSS properties (margin-inline-start) flip correctly for right-to-left.
  • Give translators context (a comment or the screen the key lives on) and test with a "pseudo-locale" that lengthens strings to find overflows.
  • Escape special characters. In vue-i18n messages @, |, {, } and $ have meaning; write a literal with {'@'} (for example an email address: "{'@'}example.com").
  • Server-rendered apps must detect the locale per request and render with the same locale in the browser, or hydration will complain (SSR). Nuxt has an official module for this (Nuxt overview).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In vue-i18n with legacy: false, how do you switch the language of the whole app?

    locale is a reactive ref. Every translated string depends on it, so changing it re-renders the whole interface.
  2. 2. Why is "Hello " + name + ", you have " + n + " messages" a poor way to build text for translation?

    Concatenation fixes the word order. A message such as "Hello {name}, you have {n} messages" can be reordered by translators.
  3. 3. What is the main benefit of lazy-loading locale files?

    Only the default language ships in the main bundle. Others are separate chunks fetched when needed.
  4. 4. Which browser API decides which plural form ('one', 'few', 'many') a number uses in a language?

    Intl.PluralRules implements each language's plural rules, so you do not have to code them yourself.
  5. 5. Which attribute should change when the interface switches to Arabic?

    dir controls the direction of layout and text flow, and lang helps screen readers and hyphenation. Set both.

Summary

  • vue-i18n gives you createI18n, $t and useI18n(); set legacy: false, a locale and a fallbackLocale.
  • Messages use and pipe-separated plural forms; the browser's Intl.PluralRules knows each language's rules.
  • Format numbers, currencies and dates with n() and d() (built on Intl), never by hand.
  • Load non-default languages with dynamic import() and setLocaleMessage, and update lang and dir when the language changes.
  • Do not concatenate sentences, do not hard-code visible text, and leave room for longer translations and right-to-left layouts.

Next: ready-made interface kits, Component Libraries: Vuetify, PrimeVue, Element Plus.