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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SFCFluentPlugin
✓ import { SFCFluentPlugin } from 'unplugin-fluent-vue/vite'
✗ import { SFCFluentPlugin } from 'unplugin-fluent-vue'
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.
ExternalFluentPlugin
✓ import { ExternalFluentPlugin } from 'unplugin-fluent-vue/webpack'
✗ import { ExternalFluentPlugin } from 'unplugin-fluent-vue'
Import path depends on your build tool (e.g., '/vite', '/webpack', '/rollup'). This example is for Webpack. This plugin supports external .ftl files.
FluentVue
✓ import FluentVue from '@fluent/vue'
✗ import { FluentVue } from 'unplugin-fluent-vue'
FluentVue is the runtime Vue plugin from the `@fluent/vue` package, not directly from `unplugin-fluent-vue`. This unplugin only handles build-time compilation.
Demonstrates how to configure unplugin-fluent-vue in a Vite project, showcasing both SFC-based and external FTL file approaches for i18n.
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { ExternalFluentPlugin, SFCFluentPlugin } from 'unplugin-fluent-vue/vite';
import path from 'path';
export default defineConfig({
plugins: [
vue(),
// Option 1: Define messages within Vue SFCs using <fluent> blocks
SFCFluentPlugin({
blockType: 'fluent', // default 'fluent'
checkSyntax: true, // default true
parseFtl: false // default false
}),
// Option 2: Define messages in external .ftl files
ExternalFluentPlugin({
baseDir: path.resolve(__dirname, 'src'), // required: base directory for Vue files
ftlDir: path.resolve(__dirname, 'src/locales'), // required: directory with ftl files
locales: ['en', 'da'], // required: list of supported locales
checkSyntax: true, // default true
parseFtl: false // default false. Set to true to pre-parse ftl at build time.
})
]
});
// Example Vue SFC (src/App.vue):
// <template>
// <p>{{ $t('greeting', { name: 'World' }) }}</p>
// </template>
// <script setup>
// import { useFluent } from 'fluent-vue';
// const { $t } = useFluent();
// </script>
// <fluent>
// greeting = Hello, { $name }!
// </fluent>
// Example FTL file (src/locales/en/messages.ftl):
// greeting = Hello, { $name } from FTL!
Errors
Common errors & fixes
Error: Cannot find module 'unplugin-fluent-vue/vite'
Incorrect bundler-specific import path or missing unplugin-fluent-vue package.
fixEnsure 'unplugin-fluent-vue' is installed. Verify the import path matches your bundler (e.g., `/vite` for Vite, `/webpack` for Webpack).
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"
Attempting to import `@fluent/vue` from `unplugin-fluent-vue`. They are separate packages.
fixInstall `@fluent/vue` as a direct dependency: `npm install @fluent/vue` and import from `@fluent/vue` instead.
[unplugin-fluent-vue] No locales defined for ExternalFluentPlugin.
The `locales` option is missing or empty in the `ExternalFluentPlugin` configuration.
fixProvide an array of locale strings to the `locales` option, e.g., `locales: ['en', 'es']`.
[Vue warn]: A plugin must either be an object with an install method or a function. Did you forget to call .use()?
Attempting to use `unplugin-fluent-vue`'s build-time plugins directly as a Vue plugin.
fixThe 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.
Audit
Dependencies
@fluent/bundlerequiredCore dependency for Fluent.js message parsing and formatting. Required for runtime message handling.
@nuxt/kitoptionalRequired only if using the plugin specifically as a Nuxt module (available since v1.3.0).