Jak ogarnąć i18n we Vue 3 z TypeScriptem i Vite

Wprowadzenie

Tłumaczenia w aplikacjach frontendowych to standard – zwłaszcza jeśli aplikacja ma trafić do międzynarodowych odbiorców. W Vue 3 zalecaną biblioteką jest vue-i18n , która wspiera pełną integrację z Composition API oraz TypeScript.

W tym poradniku pokażę, jak skonfigurować vue-i18n w projekcie opartym na Vite i TypeScript, z dynamicznym ładowaniem plików językowych i pełną kontrolą nad typami.

Krok 1: Instalacja zależności

npm install vue-i18n@9

Jeśli używasz TypeScripta, biblioteka automatycznie zapewni wsparcie typów.

Krok 2: Konfiguracja struktury katalogów

Stwórz katalog locales/ i w nim pliki np.:

src/
├─ locales/
│  ├─ en.ts
│  └─ pl.ts

Przykład pl.ts:

export default {
  hello: 'Cześć świecie',
  menu: {
    home: 'Strona główna',
    about: 'O nas',
  },
}

Przykład en.ts:

export default {
  hello: 'Hello world',
  menu: {
    home: 'Home',
    about: 'About us',
  },
}

Krok 3: Inicjalizacja vue-i18n

Stwórz plik i18n.ts w src/:

import { createI18n } from 'vue-i18n'
import pl from './locales/pl'
import en from './locales/en'

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

Krok 4: Integracja z aplikacją Vue

W pliku main.ts:

import { createApp } from 'vue'
import App from './App.vue'
import { i18n } from './i18n'

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

Krok 5: Użycie tłumaczeń w komponentach

Template

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

Script (TypeScript)

<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { t, locale } = useI18n()

const current = locale.value
const label = t('menu.home')
</script>

Krok 6: Przełączanie języka w locie

<template>
  <button @click="setLang('pl')">🇵🇱</button>
  <button @click="setLang('en')">🇬🇧</button>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { locale } = useI18n()

function setLang(lang: 'pl' | 'en') {
  locale.value = lang
}
</script>

Krok 7: Typowanie kluczy tłumaczeń (opcjonalne)

Możesz dodać typowanie t('...') z pomocą vue-i18n type-safe

Dla prostoty w tym poradniku pomijamy konfigurację vue-i18n.d.ts, ale dla większych aplikacji warto się z tym zapoznać.

Podsumowanie

Vue I18n 9 w połączeniu z Vite i TypeScriptem to zestaw pozwalający na szybką i bezpieczną implementację tłumaczeń. Dzięki wsparciu dla Composition API i dynamicznych języków możesz łatwo skalować aplikację na wiele rynków — bez nadmiaru boilerplate’u i chaosu w strukturze.

Jeśli chcesz rozszerzyć ten przykład o lazy-loading języków, integrację z localStorage lub automatyczne wykrywanie języka przeglądarki — daj znać.