Soluling home   Document home

Vue Localization and Internationalization

Vue (Wikipedia) is a very popular JavaScript framework to build browser applications. There is no built-in localization support in Vue, so you have to use a 3rd party library. The most common libraries are Vue I18n (vue-i18n) and i18next-vue. No matter which one of these libraries you use, Soluling Desktop and Soluling Cloud support Vue. This document uses Vue I18n. If you use i18next, read i18next localization.

• Add Vue I18n to your application
• Mark the strings you want to localize
• Localization process
• Load the localized resource files
• Language selection
• Samples

The end of the document contains links to get the full source code of the samples. After reading this document, we recommend reading a tutorial about how to use Soluling.

Add Vue I18n to your application

The following instructions use Vue 3 and Vue I18n 9 or later. Install Vue I18n.

npm install vue-i18n

Create a resource file that contains the strings of your original language, for example, src/locales/en.json. Each item has a key and a value.

{
  "hello": "Hello World"
}

Then create the I18n instance in src/main.js and add it to the application.

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

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

createApp(App).use(i18n).mount('#app')

locale is the active language, and fallbackLocale is the language that is used if a string has no translation in the active language.

Mark the strings you want to localize

Replace the hard coded strings of your templates with the $t function. For example, the following template has a hard coded string.

<template>
  <p>Hello World</p>
</template>

Add "Hello World" into src/locales/en.json as shown above, and change the template to

<template>
  <p>{{ $t('hello') }}</p>
</template>

$t looks up the key from the resource of the active language. If you need a string in the script part of a component, use the t function of useI18n.

import { useI18n } from 'vue-i18n'

const { t } = useI18n()
const message = t('hello')

A string can contain placeholders. Pass the values as the second parameter.

{
  "greeting": "Hello, {name}"
}

<p>{{ $t('greeting', { name: 'John' }) }}</p>

Localization process

You can localize en.json either in Soluling Desktop or in Soluling Cloud. In both cases, you get one localized resource file for each language, for example, fi.json for Finnish, in the same src/locales directory.

Desktop process

1. Start Soluling. Drag src/locales/en.json on Soluling or click the New from File or Files button and select the file.
2. If Soluling asks what kind of file it is, select Vue I18n resource file and click OK.
3. Project Wizard appears. Select English as the original language and the target languages, for example, Finnish and German, and complete the wizard.
4. Translate the project.
5. Choose Home | Build All to build the localized resource files, for example, src/locales/fi.json.

Cloud process

With Soluling Cloud, you localize the resource file in your browser: upload the file, translate it in Translate, and download the localized files. You need a Soluling account. See the available Cloud plans.

Create a project

1. Sign in at www.soluling.com and open Cloud > Dashboard for Projects, Users and Terminology.
2. Click Add a new project, then Select files and pick src/locales/en.json, or drag and drop the file onto the page. Click Create.
3. On the next page, check the project's Name. It defaults to the file's name.
4. Set the Original language to English.
5. Under Target languages, check the languages you want to translate to, for example, Finnish and German.
6. Under Source type, select Vue I18n resource file (.json). The file is also a valid generic JSON file, so make sure you pick the Vue I18n parser.
7. Click Create. The project appears on the dashboard, and its status changes to Ready once the file has been processed.

Translate the project

Click the project's green Translate button on the dashboard. Translate opens the project, and you can type the translations into the grid. Machine translation suggestions, translation memory, and spell checking are available there. You do not have to finish every language before moving on to the next step.

Get the localized files

1. In Translate's top bar, click the project's name. It opens the project's Manage page, the same page that the project's Manage button on the dashboard opens.
2. If you have translated something since the localized files were last built, the page says Localized files need to be built. Click Build localized files and wait until it finishes.
3. The Files section lists en.json with a download button for each target language. Save the localized files to the src/locales directory, named with the language code, for example, fi.json for Finnish.

Update the project

When you add or change strings in en.json, upload the new file, translate what is new or changed, and download the localized files again. On the dashboard, click the project's Update file button (the upload arrow), select the new en.json or drop it onto the page, and click Update. Existing translations are kept, so you only translate the strings that were added or changed.

The dashboard is one of four ways to use Soluling Cloud. You can also use the SoluCLI command-line tool, Soluling Desktop, or SoluMake, which can run the update and build steps in your build pipeline. See the Cloud tutorial for all of them.

Load the localized resource files

The simplest way is to import all resource files and pass them to createI18n. Use the browser's language as the initial language.

import en from './locales/en.json'
import fi from './locales/fi.json'
import de from './locales/de.json'

const language = navigator.language.split(/[-_]/)[0];  // language without region code

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

If you have many languages or large resource files, load them lazily. Then the application downloads only the resource of the language that it uses.

export async function loadLanguage(i18n, language)
{
  if (!i18n.global.availableLocales.includes(language))
  {
    const messages = await import(`./locales/${language}.json`)
    i18n.global.setLocaleMessage(language, messages.default)
  }

  i18n.global.locale.value = language
}

Language selection

Vue I18n can change the language on run time. Set the locale of the I18n instance, and all components that use $t update automatically.

<template>
  <select v-model="$i18n.locale">
    <option value="en">English</option>
    <option value="fi">suomi</option>
    <option value="de">Deutsch</option>
  </select>
</template>

If you load the resources lazily, call loadLanguage shown above instead of setting the locale directly.

Samples

GitHub and <data-dir>\Samples\Vue contain the following Vue samples:

The samples use Vue 2 and Vue I18n 8. The code in this document uses Vue 3 and Vue I18n 9 or later. The resource files (src/locales/*.json) and the Soluling projects are the same with both versions.