vue3-gettext

library4.0.0-beta.1jsnpmunverified

Vue 3 Gettext is a library for internationalizing Vue 3 applications using the gettext translation system. It provides a simple, ergonomic API for reactive translations within Vue templates and TypeScript/JavaScript code, supporting pluralization and message contexts. The package includes a CLI tool for automatic message extraction from code files, facilitating the translation workflow. Currently in a 4.0.0-beta.1 state, it is actively developed with continuous enhancements and breaking changes between major and minor alpha/beta releases. Its key differentiator is the direct integration with Vue 3's reactivity system and adherence to the established gettext standard, offering a robust alternative to other i18n solutions for projects already using or preferring gettext.

web-framework serialization

npm install vue3-gettext

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE3-GETTEXT

vue3-gettext

web-frameworkjavascriptv4.0.0-beta.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createGettext

✓ import { createGettext } from 'vue3-gettext'

✗ const { createGettext } = require('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

✓ import { useGettext } from 'vue3-gettext'

✗ 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

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

✗ import { $gettext } from 'vue3-gettext'

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

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');

Debug

Known issues

breakingCommonJS 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.

affects: >=4.0.0-alpha.6

breakingThe minimum Node.js version required has been increased to 20.

fix

Upgrade your Node.js environment to version 20.19.0 or higher.

affects: >=4.0.0-alpha.6

breakingThe `<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.

affects: >=4.0.0-alpha.2

breakingMessage 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.

affects: >=4.0.0-alpha.4

breakingThe configuration interface `GettextConfigOptions` was renamed to `Config`.

fix

Update any TypeScript interfaces or type references from `GettextConfigOptions` to `Config`.

affects: >=4.0.0-alpha.6

gotchaGlobal 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.

affects: >=4.0.0-alpha.8

Errors

Common errors & fixes

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

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)

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

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") }}`.

Upgrade

Version history

4.0.0-beta.1latest on npm

Audit

Dependencies

@vue/compiler-sfcrequiredRequired for Vue Single File Component (SFC) compilation and message extraction.

vuerequiredCore dependency for Vue 3 application development.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jshmrtn/vue3-gettext ↗

packagehttps://www.npmjs.com/package/vue3-gettext ↗

homepagehttps://jshmrtn.github.io/vue3-gettext/ ↗