Internationalization is a design process that ensures a product (a website or application) can be adapted to various languages and regions without requiring engineering changes to the source code. Think of internationalization as readiness for localization.

Setup manually

If you missed enabling i18n during yarn create quasar (or npm init quasar@latest or the pnpm or Bun equivalent) wizard, here is how you can set it up manually.

1. Install the vue-i18n dependency into your app.

$ yarn add vue-i18n

2. Create a file src/boot/i18n.js with following content:

import { defineBoot } from '#q-app/wrappers'
import { createI18n } from 'vue-i18n'
import messages from 'src/i18n'

export default defineBoot(({ app }) => {
  const i18n = createI18n({
    locale: 'en-US',
    globalInjection: true,
    messages
  })

  // Set i18n instance on app
  app.use(i18n)
})

3. Create a folder (/src/i18n/) in your app which will hold the definitions for each language that you’ll support. Example: src/i18n. Notice the “import messages from ‘src/i18n’” from step 2. This is step where you write the content that gets imported.

4. Now reference this file in quasar.config one in the boot section:

return {
  boot: [
    // ...
    'i18n'
  ],

  // ...
}

Now you are ready to use it in your pages.

Setting up Translation Blocks in your SFCs

@quasar/app-vite only

If we want to add support to the <i18n> tag inside a SFC (single file component) in a Quasar CLI project then we need to modify the existing configuration.

We first install the @intlify/unplugin-vue-i18n package:

$ yarn add --dev @intlify/unplugin-vue-i18n

Then we edit the /quasar.config file:

import { fileURLToPath } from 'node:url'

// ...

build: {
  vitePlugins: [
    ['@intlify/unplugin-vue-i18n/vite', {
      // if you want to use Vue I18n Legacy API, you need to set `compositionOnly: false`
      // compositionOnly: false,

      // if you want to use named tokens in your Vue I18n messages, such as 'Hello {name}',
      // you need to set `runtimeOnly: false`
      // runtimeOnly: false,

      ssr: ctx.modeName === 'ssr',

      // you need to set i18n resource including paths !
      include: [ fileURLToPath(new URL('./src/i18n', import.meta.url)) ]
    }]
  ]
}

How to use

Here is an example displaying the main use cases:

<template>
  <q-page>
    <!-- text interpolation, reactive -->
    {{ $t('hello') }}

    <!-- prop/attr binding, reactive -->
    <q-btn :label="$t('hello')" />

    <!-- v-html directive usage -->
    <span v-html="content"></span>
  </q-page>
</template>

<script setup>
import { computed } from 'vue'
import { useI18n } from 'vue-i18n'

const { t } = useI18n()

// bound to a static variable, non-reactive
// const staticContent = t('hello')
// bound to a reactive variable, but one-time assignment, locale changes will not update the value
// const reactiveStaticContent = ref(t('hello'))

// bound to a reactive variable, locale changes will reflect the value
const content = computed(() => t('hello'))

function notify() {
  Notify.create({
    type: 'positive',
    message: t('hello')
  })
}
</script>

Add new language

Let’s say you want to add new German language.

1. Create the new file src/i18n/de/index.js and copy there the content of the file src/i18n/en-US/index.js then make changes to the language strings.
2. Now change src/i18n/index.js and add the new de language there.

import enUS from './en-US'
import de from './de'

export default {
  'en-US': enUS,
  'de': de
}

Create language switcher

<template>
  <!-- ...... -->
  <q-select
    v-model="locale"
    :options="localeOptions"
    label="Quasar Language"
    dense
    borderless
    emit-value
    map-options
    options-dense
    style="min-width: 150px"
  />
  <!-- ...... -->
</template>

<script setup>
import { useI18n } from 'vue-i18n'

const { locale } = useI18n({ useScope: 'global' })

const localeOptions: [
  { value: 'en-US', label: 'English' },
  { value: 'de', label: 'German' }
]
</script>

UPPERCASE

Many languages, such as Greek, German and Dutch have non-intuitive rules for uppercase display, and there is an edge case that you should be aware of:

QBtn component will use the CSS text-transform: uppercase rule to automatically turn its label into all-caps. According to the MDN webdocs, “The language is defined by the lang HTML attribute or the xml:lang XML attribute.” Unfortunately, this has spotty implementation across browsers, and the 2017 ISO standard for the uppercase German eszett ß has not really entered the canon. At the moment you have two options:

1. use the prop no-caps in your label and write the string as it should appear
2. use the prop no-caps in your label and rewrite the string with toLocaleUpperCase by using the locale as detected by $q.lang.getLocale()

Detecting Locale

There’s also a method to determine user locale which is supplied by Quasar out of the box:

// outside of a Vue file
import { Lang } from 'quasar'
Lang.getLocale() // returns a string

// inside of a Vue file
import { useQuasar } from 'quasar'

setup () {
  const $q = useQuasar()
  $q.lang.getLocale() // returns a string
}