{"id":12312,"library":"unplugin-fluent-vue","title":"Fluent Vue Internationalization Unplugin","description":"unplugin-fluent-vue is a build tool plugin that integrates Fluent.js for internationalization (i18n) into Vue.js projects. It provides support for defining Fluent messages directly within Vue Single File Components (SFCs) using custom blocks, or by referencing external `.ftl` (Fluent Translation List) files. It currently stands at version 1.4.1 and sees regular maintenance releases, with the latest update in April 2026. This unplugin differentiates itself by offering a unified API for Vite, Webpack, and Rollup, leveraging the unplugin ecosystem. Key features include syntax checking for Fluent messages, optional in-build FTL parsing, and dedicated plugins for SFC-based or external file-based message definitions, making it a flexible choice for Vue i18n with Fluent.","status":"active","version":"1.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/fluent-vue/unplugin-fluent-vue","tags":["javascript","unplugin","vue","fluent-vue","ftl","fluent","webpack","vite","i18n","typescript"],"install":[{"cmd":"npm install unplugin-fluent-vue","lang":"bash","label":"npm"},{"cmd":"yarn add unplugin-fluent-vue","lang":"bash","label":"yarn"},{"cmd":"pnpm add unplugin-fluent-vue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for Fluent.js message parsing and formatting. Required for runtime message handling.","package":"@fluent/bundle","optional":false},{"reason":"Required only if using the plugin specifically as a Nuxt module (available since v1.3.0).","package":"@nuxt/kit","optional":true}],"imports":[{"note":"Import path depends on your build tool (e.g., '/vite', '/webpack', '/rollup'). This example is for Vite. Make sure to choose the correct entry point.","wrong":"import { SFCFluentPlugin } from 'unplugin-fluent-vue'","symbol":"SFCFluentPlugin","correct":"import { SFCFluentPlugin } from 'unplugin-fluent-vue/vite'"},{"note":"Import path depends on your build tool (e.g., '/vite', '/webpack', '/rollup'). This example is for Webpack. This plugin supports external .ftl files.","wrong":"import { ExternalFluentPlugin } from 'unplugin-fluent-vue'","symbol":"ExternalFluentPlugin","correct":"import { ExternalFluentPlugin } from 'unplugin-fluent-vue/webpack'"},{"note":"FluentVue is the runtime Vue plugin from the `@fluent/vue` package, not directly from `unplugin-fluent-vue`. This unplugin only handles build-time compilation.","wrong":"import { FluentVue } from 'unplugin-fluent-vue'","symbol":"FluentVue","correct":"import FluentVue from '@fluent/vue'"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport vue from '@vitejs/plugin-vue';\nimport { ExternalFluentPlugin, SFCFluentPlugin } from 'unplugin-fluent-vue/vite';\nimport path from 'path';\n\nexport default defineConfig({\n  plugins: [\n    vue(),\n    // Option 1: Define messages within Vue SFCs using <fluent> blocks\n    SFCFluentPlugin({\n      blockType: 'fluent', // default 'fluent'\n      checkSyntax: true,   // default true\n      parseFtl: false      // default false\n    }),\n    // Option 2: Define messages in external .ftl files\n    ExternalFluentPlugin({\n      baseDir: path.resolve(__dirname, 'src'), // required: base directory for Vue files\n      ftlDir: path.resolve(__dirname, 'src/locales'), // required: directory with ftl files\n      locales: ['en', 'da'], // required: list of supported locales\n      checkSyntax: true,     // default true\n      parseFtl: false        // default false. Set to true to pre-parse ftl at build time.\n    })\n  ]\n});\n\n// Example Vue SFC (src/App.vue):\n// <template>\n//   <p>{{ $t('greeting', { name: 'World' }) }}</p>\n// </template>\n// <script setup>\n// import { useFluent } from 'fluent-vue';\n// const { $t } = useFluent();\n// </script>\n// <fluent>\n// greeting = Hello, { $name }!\n// </fluent>\n\n// Example FTL file (src/locales/en/messages.ftl):\n// greeting = Hello, { $name } from FTL!","lang":"typescript","description":"Demonstrates how to configure unplugin-fluent-vue in a Vite project, showcasing both SFC-based and external FTL file approaches for i18n."},"warnings":[{"fix":"Correct `import { ... } from 'unplugin-fluent-vue/[bundler]'` where `[bundler]` is `vite`, `webpack`, or `rollup`.","message":"The import path for the unplugin changes based on your bundler. Ensure you use `/vite`, `/webpack`, or `/rollup` suffix for the import.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to v1.4.0 or newer to use the `parseFtl` option for potentially improved performance by parsing FTL files during the build process.","message":"The `parseFtl` option for `SFCFluentPlugin` and `ExternalFluentPlugin` was introduced in v1.4.0. Prior versions did not support build-time parsing of FTL, relying solely on runtime parsing.","severity":"breaking","affected_versions":"<1.4.0"},{"fix":"Install `@nuxt/kit` if you intend to use the Nuxt module functionality: `npm install @nuxt/kit` or `yarn add @nuxt/kit`.","message":"If you are using this plugin with Nuxt, you must ensure `@nuxt/kit` is installed, although it's listed as an optional peer dependency. Without it, the Nuxt module integration will not function.","severity":"gotcha","affected_versions":">=1.3.0"},{"fix":"Install `@fluent/vue` separately: `npm install @fluent/vue` and set up the FluentVue plugin in your main.ts/js.","message":"The plugin's primary role is build-time transformation. You still need the `@fluent/vue` package for the runtime integration within your Vue application (e.g., `useFluent`, `$t`).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure 'unplugin-fluent-vue' is installed. Verify the import path matches your bundler (e.g., `/vite` for Vite, `/webpack` for Webpack).","cause":"Incorrect bundler-specific import path or missing unplugin-fluent-vue package.","error":"Error: Cannot find module 'unplugin-fluent-vue/vite'"},{"fix":"Install `@fluent/vue` as a direct dependency: `npm install @fluent/vue` and import from `@fluent/vue` instead.","cause":"Attempting to import `@fluent/vue` from `unplugin-fluent-vue`. They are separate packages.","error":"Failed to resolve import \"@fluent/vue\" from \"src/main.js\". The package \"@fluent/vue\" is not exported by \"node_modules/unplugin-fluent-vue/package.json\""},{"fix":"Provide an array of locale strings to the `locales` option, e.g., `locales: ['en', 'es']`.","cause":"The `locales` option is missing or empty in the `ExternalFluentPlugin` configuration.","error":"[unplugin-fluent-vue] No locales defined for ExternalFluentPlugin."},{"fix":"The plugins from `unplugin-fluent-vue` are for your build configuration (e.g., `vite.config.js`). For runtime Vue integration, use `@fluent/vue` and its `createFluent` function.","cause":"Attempting to use `unplugin-fluent-vue`'s build-time plugins directly as a Vue plugin.","error":"[Vue warn]: A plugin must either be an object with an install method or a function. Did you forget to call .use()?"}],"ecosystem":"npm"}