Petite Vue I18n

Common errors

• Property '$n' does not exist on type 'I18n<MessageSchema, Locales, Values>'

  cause Attempting to use the number formatting API (`$n` or `n`) which is excluded from petite-vue-i18n.
  fix Remove all references to `$n` or `n`. petite-vue-i18n is translation-only. Use full vue-i18n if number formatting is needed.

• Failed to resolve directive: t

  cause The `v-t` custom directive is not included in petite-vue-i18n.
  fix Replace `v-t` directives with template interpolations like `{{ t('your.key') }}` after exposing `t` from `useI18n()` in your component's setup function.

• TypeError: Cannot read properties of undefined (reading 'nestedKey')

  cause Attempting to access a nested translation key (e.g., `t('auth.login')`) when petite-vue-i18n's default resolver only supports flat keys.
  fix Either flatten your locale messages (e.g., `auth_login: '...'`) or provide a custom message resolver function during `createI18n` initialization.

• TypeError: app.use is not a function

  cause This usually indicates that `createApp` from 'vue' was not correctly imported or called, meaning `app` is not a valid Vue application instance.
  fix Ensure you have `import { createApp } from 'vue'` and that `createApp()` is called to initialize your `app` constant before `app.use(i18n)`.

Warnings

• breaking petite-vue-i18n exclusively supports Vue 3's Composition API. Legacy Vue I18n Options API global properties like `$t` via `this` are not directly available without explicitly exposing `t` from `useI18n()` within setup.
  Fix: Migrate all i18n logic to use the Composition API's `useI18n()` hook, typically within a component's `setup` function or `<script setup>` block.
• breaking The `v-t` custom directive for template translations is entirely omitted to reduce bundle size. It will not function and may cause errors if used.
  Fix: Remove `v-t` directives. Translations in templates must be performed using interpolation, e.g., `{{ t('your.key') }}` after exposing `t` from `useI18n()`.
• breaking DateTime (`$d`, `d`) and Number Formatting (`$n`, `n`) APIs are deliberately excluded from petite-vue-i18n. Attempting to use these will result in runtime errors.
  Fix: Remove all calls to `$d`, `d`, `$n`, or `n`. If date/number formatting is required, you must migrate to the full `vue-i18n` package or implement custom formatting logic.
• gotcha By default, `petite-vue-i18n` handles only simple, flat key-value locale messages. Hierarchical messages (e.g., `messages.en.auth.login`) are not resolved without custom message resolver configurations.
  Fix: Restructure your locale messages to be flat (e.g., `auth_login: '...'`) or implement a custom message resolver function when creating the i18n instance.
• gotcha The local fallback algorithm strictly follows the array order specified in `fallbackLocale`. This differs from `vue-i18n`'s more flexible fallback strategies, which may check all available locales.
  Fix: Be aware of the strict array-order fallback. Ensure your `fallbackLocale` array reflects the precise fallback order desired.

Install

• npm install petite-vue-i18n npm
• yarn add petite-vue-i18n yarn
• pnpm add petite-vue-i18n pnpm

Imports

• createI18n
  wrong:

  const createI18n = require('petite-vue-i18n')

  correct:

  import { createI18n } from 'petite-vue-i18n'

  petite-vue-i18n is primarily designed for ESM environments. CommonJS require() is not the idiomatic way to import in modern Vue 3 projects.
• useI18n
  wrong:

  const { useI18n } = require('petite-vue-i18n')

  correct:

  import { useI18n } from 'petite-vue-i18n'

  This Composition API hook is the primary method to access i18n functionalities within Vue 3 components.
• Composer

  import type { Composer } from 'petite-vue-i18n'

  Importing the Composer type is useful for TypeScript users to type the return value of useI18n() explicitly.

Quickstart

This example demonstrates how to set up `petite-vue-i18n` with `createI18n`, use the `useI18n` hook for translations (`t`), and dynamically switch locales in a Vue 3 application.

import { createApp } from 'vue'
import { createI18n, useI18n } from 'petite-vue-i18n'

const messages = {
  en: {
    'hello world': 'Hello world from petite-vue-i18n!',
    'greeting': 'Welcome, {name}!',
    'about': 'This is a lightweight i18n solution.'
  },
  fr: {
    'hello world': 'Bonjour le monde de petite-vue-i18n !',
    'greeting': 'Bienvenue, {name} !',
    'about': 'Ceci est une solution i18n légère.'
  }
}

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

const app = createApp({
  setup() {
    const { t, locale } = useI18n()
    return { t, locale }
  },
  template: `
    <div id="app">
      <h1>{{ t('hello world') }}</h1>
      <p>{{ t('greeting', { name: 'User' }) }}</p>
      <p>{{ t('about') }}</p>
      <button @click="locale = 'fr'">Switch to French</button>
      <button @click="locale = 'en'">Switch to English</button>
    </div>
  `
})

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