@routa/i18n-vue

Vue-first adapter for the Routa i18n runtime.

This package wraps the instance-based core runtime with:

• createI18n() for Vue apps
• app.use(i18n) installation
• useI18n() and useLocale()
• reactive helpers such as computedT() and useI18nComputed()

Vue app consumers install this package directly. They do not need to install or reference @routa/i18n; the published Vue package self-contains the core runtime it uses.

Quick Start

import path from 'node:path'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { i18nPlugin } from '@routa/i18n-vue/vite-plugin'

export default defineConfig({
  plugins: [
    vue(),
    i18nPlugin({
      localesDir: path.resolve(__dirname, 'locales'),
      outputDir: path.resolve(__dirname, '.i18n'),
      sourceLocale: 'zh-CN',
      include: [path.resolve(__dirname, 'src')],
    }),
  ],
})

Locale Files

Use the same filesystem-domain layout as the core runtime:

locales/
  zh-CN/
    nav.ts
    user.ts
  en-US/
    nav.ts
    user.ts

App Installation

Create and install a Vue i18n instance:

import { createApp } from 'vue'
import App from './App.vue'
import { createI18n } from '@routa/i18n-vue'

const i18n = createI18n({
  sourceLocale: 'zh-CN',
  initialLocale: 'zh-CN',
  messages: {
    'zh-CN': {
      nav: {
        guide: 'Guide Source',
      },
    },
    'en-US': {
      nav: {
        guide: 'Guide',
      },
    },
  },
})

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

Typed Key Usage

Import generated keys from virtual:routa-i18n/keys:

import { k, nav } from 'virtual:routa-i18n/keys'
import { useI18n } from '@routa/i18n-vue'

const { t } = useI18n()

t(k.nav.guide, 'Guide')
t(nav.guide, 'Guide')

The recommended safe path is:

• t(k.xxx.xxx, ...)
• t(domain.xxx, ...)

Avoid raw string keys in application code when type safety matters.

Composition API

Use the installed instance inside components:

import { computed } from 'vue'
import { useI18n, useLocale } from '@routa/i18n-vue'
import { k } from 'virtual:routa-i18n/keys'

export function useNavTitle() {
  const { t } = useI18n()
  const locale = useLocale()

  const title = computed(() => t(k.nav.guide, 'Guide'))

  return {
    title,
    locale,
  }
}

useI18n() returns the active Vue wrapper instance.

useLocale() returns a readonly reactive locale ref. Change locale through await useI18n().setLocale(locale).

useT() returns the same typed TranslateFn as useI18n().t:

import { useT } from '@routa/i18n-vue'
import { system } from 'virtual:routa-i18n/keys'

const t = useT()
t(system.userName)

Reactive Config Helpers

For translated values created outside the template render path, wrap the whole config in a computed helper so it naturally refreshes after locale changes:

import { useI18nComputed } from '@routa/i18n-vue'
import { system } from 'virtual:routa-i18n/keys'

const columns = useI18nComputed((t) => [
  { key: 'name', title: t(system.userName) },
  { key: 'email', title: t(system.email) },
])

const chartOption = useI18nComputed((t) => ({
  title: {
    text: t(system.userGrowth),
  },
  xAxis: {
    name: t(system.month),
  },
}))

For a single translated value, use computedT():

import { computedT } from '@routa/i18n-vue'
import { system } from 'virtual:routa-i18n/keys'

const title = computedT(system.userName)
const confirmText = computedT(system.deleteUserConfirm, () => ({ name: row.value.name }))

Changing Locale

Use the installed instance to change locale:

import { useI18n } from '@routa/i18n-vue'

const i18n = useI18n()

await i18n.setLocale('en-US')
console.log(i18n.locale.value)

ICU Calls

The adapter uses the same t() overloads as the core package:

t(k.nav.guide)
t(k.nav.guide, 'Guide')
t(k.user.welcome, { name: 'Ada' })
t(k.user.welcome, 'Hello, {name}', { name: 'Ada' })

Supported ICU subset today:

• {name}
• plural
• select
• number, date, and time

Runtime Behavior

Locale lookup order:

1. current locale
2. configured fallbackLocale
3. source locale
4. call-site defaultValue
5. key path

Locale changes are reactive, so Vue render output updates after setLocale(...).

Relationship To The Core Runtime

@routa/i18n-vue is the Vue entry package. Its published runtime self-contains the core implementation so Vue projects only install @routa/i18n-vue.

@routa/i18n remains public for:

• framework-agnostic runtime access
• low-level runtime control
• non-Vue adapters such as a future React adapter

Use @routa/i18n-vue when you need:

• app.use(...)
• useI18n()
• useLocale()
• reactive refs/computed helpers
• generated key declarations that import from @routa/i18n-vue

For lower-level compiler/runtime details, see ../i18n/README.md.