{"id":6638,"date":"2025-08-07T06:00:00","date_gmt":"2025-08-07T06:00:00","guid":{"rendered":"https:\/\/poeditor.com\/blog\/?p=6638"},"modified":"2026-04-20T12:51:45","modified_gmt":"2026-04-20T12:51:45","slug":"vue-i18n","status":"publish","type":"post","link":"https:\/\/poeditor.com\/blog\/vue-i18n\/","title":{"rendered":"A complete guide to internationalizing Vue apps with vue-i18n"},"content":{"rendered":"\n
\"vue<\/figure>\n\n\n\n

If you\u2019re building Vue applications for real-world users, you\u2019ll eventually need to go beyond a single language. That means dealing with translations, formatting numbers and dates correctly, and supporting different locales.<\/p>\n\n\n\n

This is referred to as internationalization (i18n) and localization (l10n). The best way to implement it in Vue is with the vue-i18n package<\/a>.<\/p>\n\n\n\n

This guide walks through internationalizing your Vue app with vue-i18n<\/code>. You\u2019ll learn how to structure translations, wire up locale switching, and manage translations cleanly as your app grows.<\/p>\n\n\n\n

Getting started<\/h2>\n\n\n\n

Before we dive into translations and language switching, let\u2019s make sure your project is set up. If you already have a Vue 3<\/a> app running, just install the localization package:<\/p>\n\n\n\n

npm install vue-i18n<\/code><\/pre>\n\n\n\n
If you don\u2019t have a project yet, here\u2019s how to spin one up with Vite<\/a>:<\/p>\n\n\n\n
# create a new Vue 3 project with Vite\nnpm create vite@latest vue-i18n-demo -- --template vue\n\n# move into the project folder and install dependencies\ncd vue-i18n-demo\nnpm install\n\n# start the dev server\nnpm run dev\n<\/code><\/pre>\n\n\n\n
Once it\u2019s running, open src\/App.vue<\/code> and replace the default markup with something a bit more realistic:<\/p>\n\n\n\n
<template>\n  <div class=\"container\">\n    <h1>Welcome to MyApp<\/h1>\n    <p>This is a simple localized Vue app.<\/p>\n\n    <h2>Ongoing Tasks<\/h2>\n    <p>You have {{ tasksCount }} tasks.<\/p>\n  <\/div>\n<\/template>\n\n<script setup>\nconst tasksCount = 3\n<\/script><\/code><\/pre>\n\n\n\n
This gives us a basic UI to work with. Next, we\u2019ll set up vue-i18n<\/code> and start replacing these hardcoded strings with translatable text.<\/p>\n\n\n\n
Basic text translation<\/h2>\n\n\n\n
Now that localization is set up, let\u2019s add some real translations and understand how it all fits together.<\/p>\n\n\n\n
The core idea behind vue-i18n<\/code> is that instead of hard-coding text directly into your templates, you define it once using translation keys and then pull in the appropriate message depending on the current locale. This makes your app easier to scale across different languages and regions and keeps your UI clean and consistent.<\/p>\n\n\n\n
Let\u2019s start by adding a few sample messages. For now, we\u2019ll define them inline directly in main.js so it\u2019s easy to see what\u2019s happening. Later on, we\u2019ll move them to external files, which is how things usually work in production.<\/p>\n\n\n\n
Open main.js<\/code> and update it like this:<\/p>\n\n\n\n
import { createApp } from 'vue'\nimport { createI18n } from 'vue-i18n'\nimport App from '.\/App.vue'\n\nconst i18n = createI18n({<\/code><\/pre>\n\n\n\n
In the code above, we\u2019re using createI18n()<\/code> to create an i18n instance and pass in our messages \u2014 an object containing translations for each locale. Inside each locale, the translations are grouped under a namespace (app<\/code> in this case) to keep things structured and easier to manage as the app grows.<\/p>\n\n\n\n
Once that\u2019s in place, we can start using these translations in the app\u2019s template using the $t()<\/code> function, which stands for \u201ctranslate.\u201d For example:<\/p>\n\n\n\n
<template>\n  <div class=\"container\">\n    <h1>{{ $t('app.welcome') }}<\/h1>\n    <p>{{ $t('app.description') }}<\/p>\n    <p>{{ $t('app.tasks', { count: tasksCount }) }}<\/p>\n  <\/div>\n<\/template>\n\n<script setup>\nconst tasksCount = 3\n<\/script><\/code><\/pre>\n\n\n\n
Here, $t('app.welcome')<\/code> fetches the welcome message based on the active locale, while $t('app.tasks', { count: tasksCount })<\/code> shows how to pass dynamic values. This would be explained better later in this guide.<\/p>\n\n\n\n
Add a basic language switcher<\/h3>\n\n\n\n
vue-i18n exposes the current locale on $i18n.locale<\/code>, so you can bind that to a dropdown and let users switch on the fly. Like this:<\/p>\n\n\n\n
<select v-model=\"$i18n.locale\">\n  <option value=\"en\">English<\/option>\n  <option value=\"fr\">Fran\u00e7ais<\/option>\n<\/select><\/code><\/pre>\n\n\n\n
When a user picks a different language, vue-i18n automatically updates the UI. You don\u2019t need to reload the page or re-render components manually.<\/p>\n\n\n\n
\"\"\/<\/figure>\n\n\n\n
Extracting translations into JSON files<\/h2>\n\n\n\n
The inline messages<\/code> setup is fine when you’re just getting started. But once your app grows past a couple of screens, or you start supporting more than one or two languages, it’s better to split translations into dedicated JSON files.<\/p>\n\n\n\n
This keeps things clean and also makes it easier to hand off strings to translators or sync with a translation management platform later on.<\/p>\n\n\n\n
Here\u2019s a common structure:<\/p>\n\n\n\n
src\/\n\u2514\u2500 locales\/\n   \u251c\u2500 en.json\n   \u2514\u2500 fr.json<\/code><\/pre>\n\n\n\n
Each file holds a nested object of translation keys and values:<\/p>\n\n\n\n
\/\/ en.json\n{\n  \"app\": {\n    \"welcome\": \"Welcome to MyApp\",\n    \"description\": \"This is a simple localized Vue app.\",\n    \"tasks\": \"You have {count} tasks.\"\n  }\n}<\/code><\/pre>\n\n\n\n

The structure stays the same across languages:<\/p>\n\n\n\n
\/\/ fr.json\n{\n  \"app\": {\n    \"welcome\": \"Bienvenue sur MyApp\",\n    \"description\": \"Ceci est une application Vue localis\u00e9e.\",\n    \"tasks\": \"Vous avez {count} t\u00e2ches.\"\n  }\n}\n<\/code><\/pre>\n\n\n\n
Then update your main.js<\/code> to import them:<\/p>\n\n\n\n
import en from '.\/locales\/en.json'\nimport fr from '.\/locales\/fr.json'\n\nconst i18n = createI18n({\n  locale: 'en',\n  fallbackLocale: 'en',\n  messages: { en, fr }\n})\n\n<\/code><\/pre>\n\n\n\n
That\u2019s it. Now you\u2019re not hard-coding translations directly into your config, and your app is set up to scale, both in terms of code and workflow.<\/p>\n\n\n\n
Managing translations with POEditor<\/h2>\n\n\n\n
Once you start supporting multiple languages or if you’re working with other people, managing translation files manually can get tedious fast. That\u2019s where translation management platforms like POEditor<\/a> come in handy.<\/p>\n\n\n\n
Instead of editing JSON files by hand, you upload them to POEditor, where you (or your team) can manage all the translations through a web interface.<\/p>\n\n\n\n
To get started, export your existing translations into JSON (if you haven\u2019t already), then upload them to your POEditor project.<\/p>\n\n\n
\n
\"\"<\/figure>\n<\/div>\n\n\n
You can do this manually through the dashboard, or automate it with the POEditor API<\/a>. Here\u2019s what an upload request looks like using curl<\/code>:<\/p>\n\n\n\n
curl -X POST https:\/\/api.poeditor.com\/v2\/projects\/upload \\\n  -F api_token=\"your_api_token\" \\\n  -F id=\"your_project_id\" \\\n  -F updating=\"terms_translations\" \\\n  -F file=@\"src\/locales\/en.json\"\n<\/code><\/pre>\n\n\n\n
This imports your translation keys and values into POEditor so you can start translating immediately. See the upload docs<\/a> for everything you can tweak.Once your translations are done, you can export updated files<\/a> using their API too. For example, to download the French version:<\/p>\n\n\n\n
curl -X POST https:\/\/api.poeditor.com\/v2\/projects\/export \\\n  -d api_token=\"your_api_token\" \\\n  -d id=\"your_project_id\" \\\n  -d language=\"fr\" \\\n  -d type=\"json\"<\/code><\/pre>\n\n\n\n
This returns a URL where you can download the file and drop it back into src\/locales\/fr.json<\/code>. If you want to automate this step (say, as part of a deploy or CI workflow), you can build that in with a simple script.<\/p>\n\n\n\n
Now that translations are in place and your workflow is cleaned up, let\u2019s tackle the real-world stuff, like pluralization, formatting, and making sure your app speaks like a local.<\/p>\n\n\n\n
Handling dynamic values and interpolations<\/h2>\n\n\n\n
Most real-world apps need to show personalized or data-driven content. Things like \u201cWelcome back, Sarah\u201d or \u201cYou have 3 notifications.\u201d That\u2019s where interpolation comes in.<\/p>\n\n\n\n
With vue-i18n<\/code>, you can define placeholders in your translation messages using double curly braces ({{ }})<\/code>, then pass in the dynamic values when calling $t()<\/code>.<\/p>\n\n\n\n
Let\u2019s say your translation file looks like this:<\/p>\n\n\n\n
\/\/ en.json\n{\n  \"user\": {\n    \"greeting\": \"Welcome back, {{name}}!\",\n    \"notifications\": \"You have {{count}} new notifications.\"\n  }\n}<\/code><\/pre>\n\n\n\n
You can render these in your component like this:
<\/p>\n\n\n\n
<template>\n  <div>\n    <p>{{ $t('user.greeting', { name: userName }) }}<\/p>\n    <p>{{ $t('user.notifications', { count: notificationCount }) }}<\/p>\n  <\/div>\n<\/template>\n\n<script setup>\nconst userName = 'Sarah'\nconst notificationCount = 3\n<\/script><\/code><\/pre>\n\n\n\n
The {{name}}<\/code> and {{count}}<\/code> in the code above are placeholders in the translation string. When you pass { name: userName }<\/code> to $t()<\/code>, vue-i18n replaces {{name}}<\/code> with the value of userName.<\/p>\n\n\n\n
You can also use this pattern for more complex data, like dates or amounts, but we\u2019ll handle that separately when we talk about formatting.<\/p>\n\n\n\n
Pluralization and choice formatting<\/h2>\n\n\n\n
Plural rules vary wildly across languages. In English, it\u2019s straightforward, for example, \u201c1 item\u201d vs. \u201c2 items.\u201d But some languages use different forms for 0, 1, 2\u20134, or even for numbers that end in specific digits. <\/p>\n\n\n\n
Trying to handle that manually with if statements or ternaries quickly becomes a mess. Luckily, vue-i18n<\/code> handles all of this for you using CLDR plural rules, the same standard behind most modern localization systems. <\/p>\n\n\n\n
It knows English only needs two forms (one<\/code> and other<\/code>), while Arabic or Russian might require four or five. <\/p>\n\n\n\n
Here\u2019s a simple example:<\/p>\n\n\n\n
\/\/ en.json\n{\n  \"cart\": {\n    \"items\": \"No items | One item | {count} items\"\n  }\n}<\/code><\/pre>\n\n\n\n
This is a pipe-separated plural rule:<\/p>\n\n\n\n