{"id":12626,"library":"vue3-gettext","title":"Vue 3 Gettext","description":"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.","status":"active","version":"4.0.0-beta.1","language":"javascript","source_language":"en","source_url":"https://github.com/jshmrtn/vue3-gettext","tags":["javascript","gettext","vue","vue3","internationalization","i18n","translation","l10n","typescript"],"install":[{"cmd":"npm install vue3-gettext","lang":"bash","label":"npm"},{"cmd":"yarn add vue3-gettext","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue3-gettext","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Vue Single File Component (SFC) compilation and message extraction.","package":"@vue/compiler-sfc","optional":false},{"reason":"Core dependency for Vue 3 application development.","package":"vue","optional":false}],"imports":[{"note":"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.","wrong":"const { createGettext } = require('vue3-gettext')","symbol":"createGettext","correct":"import { createGettext } from 'vue3-gettext'"},{"note":"Used for accessing translation functions inside Vue composition API setup functions. It's a named export, not a default export.","wrong":"import useGettext from 'vue3-gettext'","symbol":"useGettext","correct":"import { useGettext } from 'vue3-gettext'"},{"note":"While `$gettext` is exposed on the Vue instance, it is not directly importable as a named export. For composition API, use `const { $gettext } = useGettext()`.","wrong":"import { $gettext } from 'vue3-gettext'","symbol":"$gettext","correct":"This is typically accessed via `this.$gettext` in options API components or directly in templates."}],"quickstart":{"code":"import { createApp } from 'vue';\nimport { createGettext } from 'vue3-gettext';\n\nconst app = createApp({\n  template: `\n    <div>\n      <p>{{ $gettext(\"Welcome, %{name}!\") }}</p>\n      <p>{{ $gettext(\"You have %{count} new message.\", \"You have %{count} new messages.\", 1, { count: 1 }) }}</p>\n      <p>{{ $gettext(\"Current locale: %{locale}\", { locale: currentLocale }) }}</p>\n      <button @click=\"changeLocale('en')\">English</button>\n      <button @click=\"changeLocale('es')\">Español</button>\n    </div>\n  `,\n  setup() {\n    const { current } = useGettext();\n    const currentLocale = ref(current.value);\n\n    const changeLocale = (newLocale) => {\n      current.value = newLocale;\n      currentLocale.value = newLocale;\n    };\n    return { currentLocale, changeLocale };\n  }\n});\n\nconst gettext = createGettext({\n  defaultLocale: 'en',\n  availableLocales: {\n    en: 'English',\n    es: 'Español'\n  },\n  translations: {\n    es: {\n      'Welcome, %{name}!': '¡Bienvenido, %{name}!',\n      'You have %{count} new message.': [\n        'Tienes %{count} nuevo mensaje.',\n        'Tienes %{count} nuevos mensajes.'\n      ],\n      'Current locale: %{locale}': 'Idioma actual: %{locale}'\n    }\n  }\n});\n\napp.use(gettext);\napp.mount('#app');","lang":"typescript","description":"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."},"warnings":[{"fix":"Migrate all `require()` statements to `import` statements. Ensure your project is configured for ESM.","message":"CommonJS outputs have been removed. Applications must use ESM imports for `vue3-gettext`.","severity":"breaking","affected_versions":">=4.0.0-alpha.6"},{"fix":"Upgrade your Node.js environment to version 20.19.0 or higher.","message":"The minimum Node.js version required has been increased to 20.","severity":"breaking","affected_versions":">=4.0.0-alpha.6"},{"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.","message":"The `<translate>` component and `v-translate` directive have been removed.","severity":"breaking","affected_versions":">=4.0.0-alpha.2"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0-alpha.4"},{"fix":"Update any TypeScript interfaces or type references from `GettextConfigOptions` to `Config`.","message":"The configuration interface `GettextConfigOptions` was renamed to `Config`.","severity":"breaking","affected_versions":">=4.0.0-alpha.6"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0-alpha.8"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use CommonJS `require()` syntax or an outdated module resolver with `vue3-gettext` v4+, which is ESM-only.","error":"Module not found: Can't resolve 'vue3-gettext' in '...' or 'require is not defined'"},{"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).","cause":"TypeScript is not correctly augmenting the Vue instance types, or the `vue3-gettext` plugin is not properly installed or configured.","error":"Property '$gettext' does not exist on type 'ComponentPublicInstance<...>' (TypeScript error)"},{"fix":"Remove the `<translate>` component and `v-translate` directive. Use the `$gettext` helper function directly in templates: `{{ $gettext(\"Your message\") }}`.","cause":"Using the `<translate>` component or `v-translate` directive which were removed in v4.","error":"[Vue warn]: Failed to resolve component: translate"}],"ecosystem":"npm"}