Vue 3 Gettext

Common errors

• Module not found: Can't resolve 'vue3-gettext' in '...' or 'require is not defined'

  cause Attempting to use CommonJS `require()` syntax or an outdated module resolver with `vue3-gettext` v4+, which is ESM-only.
  fix Change `require('vue3-gettext')` to `import { ... } from 'vue3-gettext'`. Ensure your project uses an ESM-compatible build setup (e.g., `"type": "module"` in `package.json`).

• Property '$gettext' does not exist on type 'ComponentPublicInstance<...>' (TypeScript error)

  cause TypeScript is not correctly augmenting the Vue instance types, or the `vue3-gettext` plugin is not properly installed or configured.
  fix Verify that `app.use(gettext)` is called after `createApp()`. Ensure your `tsconfig.json` is set up to include the type declarations from `vue3-gettext` (e.g., check `include` array and ensure `node_modules` is not excluded).

• [Vue warn]: Failed to resolve component: translate

  cause Using the `<translate>` component or `v-translate` directive which were removed in v4.
  fix Remove the `<translate>` component and `v-translate` directive. Use the `$gettext` helper function directly in templates: `{{ $gettext("Your message") }}`.

Warnings

• breaking CommonJS outputs have been removed. Applications must use ESM imports for `vue3-gettext`.
  Fix: Migrate all `require()` statements to `import` statements. Ensure your project is configured for ESM.
• breaking The minimum Node.js version required has been increased to 20.
  Fix: Upgrade your Node.js environment to version 20.19.0 or higher.
• breaking The `<translate>` component and `v-translate` directive have been removed.
  Fix: Replace usages of `<translate>` component and `v-translate` directive with the `$gettext` helper function directly in templates or via `useGettext` in script setup blocks.
• breaking Message IDs are no longer trimmed and line endings are normalized from CRLF to LF. This may affect existing translation files if they relied on automatic trimming or varied line endings.
  Fix: Review your existing `.po` and `.pot` files. Re-extract messages and carefully merge translations, ensuring consistency in message IDs and line endings to avoid broken translations.
• breaking The configuration interface `GettextConfigOptions` was renamed to `Config`.
  Fix: Update any TypeScript interfaces or type references from `GettextConfigOptions` to `Config`.
• gotcha Global types for Vue instances (`this.$gettext`) are augmented in both `@vue/runtime-core` and `vue` to improve compatibility across different project setups. If you encounter TypeScript errors regarding `$gettext` not existing, check your `tsconfig.json` references.
  Fix: Ensure your `tsconfig.json` includes `vue` and/or `@vue/runtime-core` types, and that `vue3-gettext`'s global type declarations are being picked up correctly by your TypeScript setup.

Install

• npm install vue3-gettext npm
• yarn add vue3-gettext yarn
• pnpm add vue3-gettext pnpm

Imports

• createGettext
  wrong:

  const { createGettext } = require('vue3-gettext')

  correct:

  import { createGettext } from 'vue3-gettext'

  This is the primary way to initialize the Gettext plugin in your Vue application. CommonJS outputs were removed in v4.0.0-alpha.6, so use ESM imports only.
• useGettext
  wrong:

  import useGettext from 'vue3-gettext'

  correct:

  import { useGettext } from 'vue3-gettext'

  Used for accessing translation functions inside Vue composition API setup functions. It's a named export, not a default export.
• $gettext
  wrong:

  import { $gettext } from 'vue3-gettext'

  correct:

  This is typically accessed via `this.$gettext` in options API components or directly in templates.

  While `$gettext` is exposed on the Vue instance, it is not directly importable as a named export. For composition API, use `const { $gettext } = useGettext()`.

Quickstart

This example demonstrates how to initialize vue3-gettext, use $gettext for singular and plural translations in a template, and dynamically change the locale using `useGettext` in the setup function.

import { createApp } from 'vue';
import { createGettext } from 'vue3-gettext';

const app = createApp({
  template: `
    <div>
      <p>{{ $gettext("Welcome, %{name}!") }}</p>
      <p>{{ $gettext("You have %{count} new message.", "You have %{count} new messages.", 1, { count: 1 }) }}</p>
      <p>{{ $gettext("Current locale: %{locale}", { locale: currentLocale }) }}</p>
      <button @click="changeLocale('en')">English</button>
      <button @click="changeLocale('es')">Español</button>
    </div>
  `,
  setup() {
    const { current } = useGettext();
    const currentLocale = ref(current.value);

    const changeLocale = (newLocale) => {
      current.value = newLocale;
      currentLocale.value = newLocale;
    };
    return { currentLocale, changeLocale };
  }
});

const gettext = createGettext({
  defaultLocale: 'en',
  availableLocales: {
    en: 'English',
    es: 'Español'
  },
  translations: {
    es: {
      'Welcome, %{name}!': '¡Bienvenido, %{name}!',
      'You have %{count} new message.': [
        'Tienes %{count} nuevo mensaje.',
        'Tienes %{count} nuevos mensajes.'
      ],
      'Current locale: %{locale}': 'Idioma actual: %{locale}'
    }
  }
});

app.use(gettext);
app.mount('#app');