Laravel Localization To Vue Laravel Package

Getting Started

This package is a build-time generator, not a runtime dependency: it reads your Laravel lang/ files and emits a JS/JSON bundle that vue-i18n consumes. Treat it accordingly.

1. Install as a dev dependency (nothing needs it at runtime):

   composer require --dev kg-bot/laravel-localization-to-vue
   

2. Publish the config and read it before running anything — the defaults were written in the Laravel Mix era and often point at resources/assets/js:

   php artisan vendor:publish
   # then open config/laravel-localization-to-vue.php
   

   Check two keys first: the search directories (should include your lang/ path — resources/lang pre-Laravel 9, lang/ after) and the output path.
3. Point the output at your Vite-era asset directory (e.g. resources/js/locales/) and generate:

   php artisan vue-i18n:generate
   

4. First use case — wire the generated file into vue-i18n in app.js:

   import { createApp } from 'vue'
   import { createI18n } from 'vue-i18n'
   import messages from './locales/vue-i18n-locales.generated.js'
   
   const i18n = createI18n({
     locale: document.documentElement.lang || 'en',
     messages,
   })
   createApp(App).use(i18n).mount('#app')
   

If you're on Laravel 11/12, v2.3 and v2.4 are interchangeable for you — v2.4 only widens the framework constraint and applies StyleCI formatting. Upgrade is a drop-in; no config or output changes.

Implementation Patterns

Generate as part of the build, not by hand. The most common failure mode is a stale generated file. Hook it into package.json:

"scripts": {
  "i18n": "php artisan vue-i18n:generate",
  "dev": "npm run i18n && vite",
  "build": "npm run i18n && vite build"
}

Watch mode during development. The package has no file watcher. Either re-run the artisan command manually, or add a watcher over lang/ (chokidar, nodemon --watch lang --exec "php artisan vue-i18n:generate") so new keys show up without a browser refresh killing your flow.

CI guard against drift. If you commit the generated file (recommended for apps that deploy JS separately from PHP), assert it's current:

php artisan vue-i18n:generate
git diff --exit-code resources/js/locales || (echo "Locales out of date" && exit 1)

Multiple search directories for modular lang files. Large apps split translations across lang/, a domain package, and vendor/ overrides. List each in the config's search directories rather than maintaining a second export step.

Lazy-load per locale once the bundle gets big — generate to one file per locale and dynamic-import in the router/i18n setup, rather than shipping every language to every user:

const messages = { en: await import('./locales/en.js') }

Blade + Vue share the same source. Because output derives from lang/, __('messages.welcome') in Blade and $t('messages.welcome') in Vue stay in sync by construction. Keep that invariant: never hand-edit the generated bundle, and route all user-facing strings through lang/.

Server-provided locale. Emit the active locale into the page (meta tag or window.__LOCALE__) so the client's initial createI18n({ locale }) matches what Laravel resolved — otherwise you get a flash of the wrong language on first paint.

Gotchas and Tips

• Placeholder syntax mismatch. Laravel uses :name; vue-i18n uses {name}. The generator does not rewrite these — a string like Welcome :name renders literally with a dangling colon in Vue. Standardise on {name} in lang/ (Laravel's replacer tolerates it) or post-process the output.
• Pluralisation conflicts. Laravel's apple|apples pipe-separated form collides with vue-i18n's own | plural syntax and its {count} requirement. Laravel's simple two-form plurals often survive, but anything with explicit ranges ({0} none|{1} one|[2,*] many) must be authored in vue-i18n syntax and loses Laravel-side correctness. Test pluralised keys explicitly.
• Nested arrays vs. flat keys. PHP return ['a' => ['b' => 'c']] becomes a nested object; vue-i18n resolves a.b against it fine, but a literal dotted key ('a.b' => 'c') will not resolve as expected. Avoid dots inside key names.
• Default output path is stale. On a fresh install, verify the generated file actually landed in resources/js/... and not resources/assets/js/.... Vite will silently fail to resolve the import and you'll blame the wrong thing.
• env() in the published config breaks under config:cache. If you customise paths with env(), switch to literals or config()-safe values — deploying with a cached config otherwise yields an empty or wrong output path.
• Re-publish/merge the config after upgrading. New releases occasionally add config keys; your old published file silently lacks them. Diff vendor/kg-bot/.../config/ against yours after each bump. (Not needed for v2.4 — config is unchanged.)
• Deployment ordering. If the generated JS is gitignored, the artisan step must run before the frontend build on every environment, including CI. If it's committed, never let the build step rewrite it on the server.
• Debugging an empty bundle: confirm the search directories are absolute (base_path('lang')) and that your lang files return arrays/JSON as expected. dd() the output file contents — an empty object almost always means the directory scan found nothing.
• Maintenance signal. Recent releases have been automated compatibility PRs (Laravel 13 support, StyleCI) rather than feature work. That's fine for a stable generator, but budget for writing your own watcher/splitting logic rather than waiting on upstream, and pin the major version in composer.json.
• Extension point: everything meaningful is in the published config — search directories, extensions, and output path. There's no event or formatter hook, so custom transformation (placeholder rewriting, key flattening) belongs in a small post-generation script you own, run right after vue-i18n:generate.