vite-plugin-laravel-translations

0.3.1 verified Mon Apr 27 auth: no javascript

Vite plugin that retrieves Laravel PHP translation files and makes them available as a global JSON variable (`import.meta.env.VITE_LARAVEL_TRANSLATIONS`) for use with i18n frameworks like vue-i18n or react-i18next. Version 0.3.1 supports Vite 3–6 and Node >=12. It uses Vite-specific hooks (`config`, `handleHotUpdate`) and cannot be used as a Rollup plugin. Key differentiators: automatic PHP-to-JSON conversion, HMR support for translation files, and optional namespacing for React compatibility. Alternative to manual JSON generation or PHP-based solutions like `laravel-vue-i18n`.

Common errors

error require() of ES Module /path/to/node_modules/vite-plugin-laravel-translations/index.js not supported. ↓

cause Package is ESM-only; CommonJS require() fails.

fix

Use ES import syntax: import laravelTranslations from 'vite-plugin-laravel-translations'

error VITE_LARAVEL_TRANSLATIONS is not defined / undefined ↓

cause The env variable is only available after the plugin runs; if accessed before plugin execution or in plain Node scripts.

fix

Ensure the plugin is added to the Vite config and access import.meta.env.VITE_LARAVEL_TRANSLATIONS inside your app (not in vite.config.js).

error Cannot find module 'vite-plugin-laravel-translations' ↓

cause Package not installed or mismatched peer dependency (vite version).

fix

Run npm i vite-plugin-laravel-translations and ensure vite peer dependency is satisfied.

error Uncaught TypeError: laravelTranslations is not a function ↓

cause Default import not used correctly (e.g., `import * as laravelTranslations`).

fix

Use default import: import laravelTranslations from 'vite-plugin-laravel-translations'

Warnings

breaking Plugin uses Vite-specific hooks (config & handleHotUpdate) and cannot be used as a Rollup plugin. ↓

fix Use only with Vite. Do not attempt to use with Rollup or other bundlers.

gotcha The injected variable is `import.meta.env.VITE_LARAVEL_TRANSLATIONS`, not `process.env.VITE_LARAVEL_TRANSLATIONS`. ↓

fix Always use import.meta.env in your application code.

gotcha Dynamic import in v0.1.5+ requires accessing .default after await import(). ↓

fix Use `const laravelTranslations = (await import('vite-plugin-laravel-translations')).default`

deprecated The `includeJson` option is marked as 'TBC' (To Be Confirmed) in the README - behavior may change. ↓

fix Set `includeJson: false` explicitly until future clarification.

gotcha Plugin indexes PHP files from `resources/lang/` by default. Ensure your Laravel structure matches. ↓

fix Verify translations are in `resources/lang/{locale}/` or adjust as needed; custom paths not documented.

breaking Peer dependency vite is required; install failures may occur if version outside ^3.2.11 || ^4.0.0 || ^5.1.3 || ^6.0. ↓

fix Install a compatible vite version (e.g., npm i vite@^5.1.3).

Install

npm install vite-plugin-laravel-translations

yarn add vite-plugin-laravel-translations

pnpm add vite-plugin-laravel-translations

Imports

default (plugin)

wrong

const laravelTranslations = require('vite-plugin-laravel-translations')

correct

import laravelTranslations from 'vite-plugin-laravel-translations'

The package is ESM-only; CommonJS require() will fail. Use default import.

dynamic import (v0.1.5+)

wrong

const laravelTranslations = await import('vite-plugin-laravel-translations')

correct

const laravelTranslations = (await import('vite-plugin-laravel-translations')).default

When using dynamic import, you must access .default because the module exports default.

import.meta.env.VITE_LARAVEL_TRANSLATIONS
wrong
```
const messages = process.env.VITE_LARAVEL_TRANSLATIONS
```
correct
```
const messages = import.meta.env.VITE_LARAVEL_TRANSLATIONS
```
This is a Vite env variable injected at build time, not a Node.js environment variable. Use import.meta.env.

Quickstart

Shows basic Vite plugin setup and Vue 3 i18n integration using the injected env variable.

// vite.config.js
import { defineConfig } from 'vite';
import laravelTranslations from 'vite-plugin-laravel-translations';

export default defineConfig({
  plugins: [
    laravelTranslations({
      // Include Laravel JSON translation files (e.g., resources/lang/vendor/*.json)
      includeJson: false,
      // Namespace for React i18next compatibility (e.g., 'translation')
      namespace: false,
    }),
  ],
});

// resources/js/app.js (Vue 3 example)
import { createApp } from 'vue';
import { createI18n } from 'vue-i18n';

const i18n = createI18n({
  locale: 'en',
  fallbackLocale: 'en',
  messages: import.meta.env.VITE_LARAVEL_TRANSLATIONS,
});

const app = createApp({});
app.use(i18n);
app.mount('#app');