Vue i18n is the official internationalization plugin for Vue.js. You install vue-i18n, create message objects or JSON files for each language, register the plugin with createI18n, and use the $t function or the useI18n composable in templates and scripts. It supports plurals, number and date formats, lazy loading of locales and fallback languages, which covers most multilingual Vue 3 apps.
This guide shows a practical Vue 3 setup with vue-i18n, explains the features you will use most, and covers how to manage translation files when the app grows.
What Is Vue I18n?
Vue I18n is maintained by the Intlify project and is the standard choice for Vue 2 and Vue 3 projects. The official Vue I18n documentation covers every API. In short, it keeps your translated messages outside your components, picks the active locale, and formats messages with variables, plurals and dates. If the term internationalization is new, our explanation of internationalization vs localization is a good starting point.
Install and Configure Vue I18n in Vue 3
1. Install the package
Add vue-i18n to your project with npm, yarn or pnpm. Use the version that matches your Vue major version, which is v9 or newer for Vue 3.
2. Create the i18n instance
Call createI18n with a default locale, a fallbackLocale and your messages. For new Vue 3 projects, use the Composition API mode with legacy: false, so useI18n works inside <script setup>.
3. Register the plugin
Install it in your app entry file with app.use(i18n). After that, every component can call $t('key') in templates.
4. Use translations in components
In templates, write {{ $t('home.title') }}. In scripts, use const { t, locale } = useI18n() and call t('home.title'). Change language by setting locale.value = 'de'.
Core Vue I18n Features
| Feature | What it does | Typical use |
|---|---|---|
| Named interpolation | Inserts variables into messages | "Hello, {name}" |
| Pluralization | Chooses the right form by count | "no items | one item | {count} items" |
| Number formatting | Formats currency and percentages per locale | Prices and statistics |
| Datetime formatting | Formats dates per locale | Orders, comments, events |
| Component interpolation | Embeds links or bold text inside a message | Terms of service sentences |
| Lazy loading | Loads a language file only when needed | Smaller initial bundle |
| Fallback locale | Uses another language if a key is missing | Partially translated releases |
For complex plural rules in languages such as Polish, Russian and Arabic, review ICU MessageFormat, which explains why "one" and "other" are not enough for many languages.
How to Organize Translation Files
Keep one JSON file per language, with nested keys grouped by feature, for example auth.login.title and cart.summary.total. Avoid keys that repeat the English text, because the source text will change while the key should stay stable. Keep messages as whole sentences with placeholders, never fragments that you glue together in code. Save files as UTF-8 so accents and non-Latin scripts display correctly, as described in our guide to character encoding and UTF-8.
Vue I18n vs Other Frontend i18n Options
| Framework | Common library | Learn more |
|---|---|---|
| Vue 3 | vue-i18n | This guide |
| React | react-i18next, react-intl | React i18n with react-i18next |
| Angular | Built-in i18n, Transloco | Angular i18n guide |
| Flutter | gen-l10n with ARB files | Flutter localization |
Common Vue I18n Mistakes
- Concatenating text. Strings like
$t('hello') + namebreak word order in other languages. - Forgetting the fallback locale. Users otherwise see raw keys when a translation is missing.
- Bundling all languages. Load locales lazily when you support many languages.
- Not testing long text. Use pseudo-localization to see how layouts handle longer translations.
- Editing JSON by hand. Missing commas and duplicated keys cause runtime errors.
Manage Vue Translations Without Editing JSON
As soon as you have more than two languages, the best practice is to treat the English JSON file as the source of truth and let a translation platform handle the rest. The platform reads the file, pre-translates with AI, applies translation memory and glossary, and sends approved translations back to your repository. This is the core of continuous localization. A software localization workflow with repository sync keeps translators away from your code and keeps developers away from spreadsheets. For file-level details, read how to translate a JSON file without breaking your keys.
Frequently Asked Questions
Is vue-i18n the official Vue library?
It is the most widely used i18n plugin for Vue and is maintained by the Intlify project, which works closely with the Vue ecosystem.
How do I switch language in Vue 3?
Use useI18n and set locale.value to a new locale code. Save the choice in local storage or a cookie so it persists.
Can I use vue-i18n with Nuxt?
Yes. The Nuxt i18n module builds on vue-i18n and adds routing, SEO tags and lazy loading.
Localize Your Vue App With WordBeam
WordBeam syncs your Vue JSON files, translates with several AI engines, enforces your glossary and shows translators each string in context. Explore UI translations or start a free trial with 14 days and 10,000 words.