Better Laravel Translator

Enhanced Laravel translation support for Vite with glob patterns and module namespacing.

About

This package builds on the excellent work of laravel-translator-js by Sergio Brighenti. We've added several enhancements while maintaining full compatibility with the original API.

What We've Added

• Glob Pattern Support: Use patterns like app-modules/**/lang to automatically find translation directories
• Module Namespacing: Optional namespacing to organize translations by module
• Cleaner Output Structure: Translations without the php/json separation
• Selective File Loading: Only processes files that match Laravel translation patterns

📦 Installation

npm install -D better-laravel-translator
# or
yarn add -D better-laravel-translator
# or
pnpm add -D better-laravel-translator

🚀 Usage

Basic Setup

// vite.config.js
import { defineConfig } from 'vite'
import betterLaravelTranslator from 'better-laravel-translator/vite'

export default defineConfig({
    plugins: [
        betterLaravelTranslator({
            langPath: 'lang' // default Laravel path
        })
    ],
})

Using Glob Patterns

betterLaravelTranslator({
    langPath: 'lang',
    additionalLangPaths: [
        'app-modules/**/lang',     // Find all module lang directories
        'packages/*/resources/lang' // Find package translations
    ]
})

Module Namespacing

When you have multiple modules with their own translations:

betterLaravelTranslator({
    langPath: 'lang',
    additionalLangPaths: ['app-modules/**/lang'],
    namespaceModules: true // Enable module namespacing
})

This creates a structure like:

{
    "en": {
        // Root translations
        "messages": { "welcome": "Welcome" },
        
        // Module translations
        "modules": {
            "user": {
                "profile": { "name": "Name" }
            },
            "billing": {
                "invoices": { "paid": "Paid" }
            }
        }
    }
}

Automatic Locale Detection

The package automatically detects your locale from Laravel's environment variables. Simply add these to your .env file:

# Laravel's locale settings
APP_LOCALE=es
APP_FALLBACK_LOCALE=en

# Make them available to Vite/frontend (required)
VITE_APP_LOCALE="${APP_LOCALE}"
VITE_APP_FALLBACK_LOCALE="${APP_FALLBACK_LOCALE}"

That's it! The package will automatically use es as the locale. No code changes needed.

In Your Application

All the translation functions work exactly as in the original package:

import { __, trans, setLocale } from 'better-laravel-translator'

// Translations automatically use VITE_APP_LOCALE from .env
console.log(__('messages.welcome'))  // Shows Spanish translation
console.log(trans('validation.required', { attribute: 'email' }))

// With module namespacing
console.log(__('modules.user.profile.name'))

// You can still manually change locale if needed
setLocale('fr')

📋 Configuration Options

{
    // Primary translation directory (default: 'lang')
    langPath?: string
    
    // Additional paths to scan (supports glob patterns)
    additionalLangPaths?: string[]
    
    // Enable module namespacing (default: false)
    namespaceModules?: boolean
    
    // Only load specific locales (default: all)
    locales?: string[]
    
    // Include JSON translation files (default: true)
    includeJson?: boolean
    
    // Include PHP translation files (default: true)
    includePhp?: boolean
}

🔧 Vue.js Integration

The Vue plugin works exactly as in the original package:

import { createApp } from 'vue'
import { laravelTranslatorVue } from 'better-laravel-translator/vue'

const app = createApp()
app.use(laravelTranslatorVue)

Then in your components:

<template>
    <div>{{ $t('messages.welcome') }}</div>
</template>

🌟 Features

Selective File Loading

Unlike the original package that loads all JSON files, we only load:

• PHP files in locale directories: lang/en/*.php
• JSON files named by locale: lang/en.json

This means configuration files like composer.json or package.json are never included in your translation bundle.

Clean Output Structure

The original package separates PHP and JSON translations:

// Original structure
{
    "en": {
        "php": { "messages": {...} },
        "json": { "Welcome": "Welcome" }
    }
}

// Our structure
{
    "en": {
        "messages": {...},
        "Welcome": "Welcome"
    }
}

🔄 Migration from Original Package

Migrating is straightforward:

// Before (laravel-translator)
laravelTranslator({
    langPath: 'resources/lang',
    additionalLangPaths: [
        './app-modules/user/lang',
        './app-modules/billing/lang',
        './app-modules/admin/lang'
    ]
})

// After (better-laravel-translator) 
betterLaravelTranslator({
    langPath: 'resources/lang',
    additionalLangPaths: [
        'app-modules/**/lang' // One pattern finds all modules!
    ],
    namespaceModules: true // Optional: prevent conflicts
})

The translation functions remain the same:

import { __, trans, setLocale } from 'better-laravel-translator'
// No code changes needed!

🤝 Credits

This package is built on top of laravel-translator-js by Sergio Brighenti. We're grateful for his work that made this package possible.

📄 License

MIT License - see the LICENSE file for details.