Fluent Vue Internationalization Unplugin

Common errors

• Error: Cannot find module 'unplugin-fluent-vue/vite'

  cause Incorrect bundler-specific import path or missing unplugin-fluent-vue package.
  fix Ensure '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"

  cause Attempting to import `@fluent/vue` from `unplugin-fluent-vue`. They are separate packages.
  fix Install `@fluent/vue` as a direct dependency: `npm install @fluent/vue` and import from `@fluent/vue` instead.

• [unplugin-fluent-vue] No locales defined for ExternalFluentPlugin.

  cause The `locales` option is missing or empty in the `ExternalFluentPlugin` configuration.
  fix Provide 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()?

  cause Attempting to use `unplugin-fluent-vue`'s build-time plugins directly as a Vue plugin.
  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.

Warnings

• gotcha The import path for the unplugin changes based on your bundler. Ensure you use `/vite`, `/webpack`, or `/rollup` suffix for the import.
  Fix: Correct `import { ... } from 'unplugin-fluent-vue/[bundler]'` where `[bundler]` is `vite`, `webpack`, or `rollup`.
• breaking 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.
  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.
• gotcha 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.
  Fix: Install `@nuxt/kit` if you intend to use the Nuxt module functionality: `npm install @nuxt/kit` or `yarn add @nuxt/kit`.
• gotcha 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`).
  Fix: Install `@fluent/vue` separately: `npm install @fluent/vue` and set up the FluentVue plugin in your main.ts/js.

Install

• npm install unplugin-fluent-vue npm
• yarn add unplugin-fluent-vue yarn
• pnpm add unplugin-fluent-vue pnpm

Imports

• SFCFluentPlugin
  wrong:

  import { SFCFluentPlugin } from 'unplugin-fluent-vue'

  correct:

  import { SFCFluentPlugin } from 'unplugin-fluent-vue/vite'

  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
  wrong:

  import { ExternalFluentPlugin } from 'unplugin-fluent-vue'

  correct:

  import { ExternalFluentPlugin } from 'unplugin-fluent-vue/webpack'

  Import path depends on your build tool (e.g., '/vite', '/webpack', '/rollup'). This example is for Webpack. This plugin supports external .ftl files.
• FluentVue
  wrong:

  import { FluentVue } from 'unplugin-fluent-vue'

  correct:

  import FluentVue from '@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.

Quickstart

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!