sirgrimorum/jslocalization

Put localization translations in js

1.3.4 2026-03-02 20:48 UTC

Requires

• php: ^8.2
• laravel/framework: ^9.0|^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0

MIT

• sirgrimorum

README

Expose Laravel translation files and Eloquent models to JavaScript with a single line. Bind PHP i18n arrays to window globals so your frontend code shares the same translations and data as your backend — no AJAX calls, no duplication.

Features

• Translation binding — publish any Laravel language file to a JavaScript global variable
• Model/collection binding — serialize any Eloquent model, collection, or array to a JavaScript variable
• Nested JS object creation — nested groups are created safely without clobbering existing keys
• Static method support — call Auth::user(), method chains, or static properties directly from the Blade directive
• Zero configuration required — works out of the box with sensible defaults

Requirements

• PHP >= 8.2
• Laravel >= 9.0

Installation

composer require sirgrimorum/jslocalization

Publish configuration (optional)

php artisan vendor:publish --provider="Sirgrimorum\JSLocalization\JSLocalizationServiceProvider" --tag=config

Publishes config/sirgrimorum/jslocalization.php.

Configuration

config/sirgrimorum/jslocalization.php

return [
    // View that receives the injected <script> tags (used for auto-injection)
    'bind_trans_vars_to_this_view' => 'layouts.app',

    // Default lang group to expose (the array key inside the language file)
    'trans_group' => 'messages',

    // Global JS variable name that holds all translations
    'default_base_var' => 'translations',

    // Path to language files
    'default_lang_path' => '/resources/lang/',
];

Usage

Bind a translation file to JavaScript

{{-- Exposes resources/lang/{locale}/messages.php as window.translations.messages --}}
@jslocalization('messages')

{{-- Expose only a specific group within the file --}}
@jslocalization('messages', 'errors')

{{-- Use a custom JS variable name --}}
@jslocalization('messages', 'errors', 'myApp')

The directive outputs a <script> tag:

<script>
window.translations = window.translations || {};
translations.messages = { "welcome": "Welcome!", "errors": { ... } };
</script>

Use translations in JavaScript

// After @jslocalization('messages')
console.log(translations.messages.welcome);  // "Welcome!"
alert(translations.messages.errors.not_found); // "Not found"

Bind a model to JavaScript

{{-- Serialize the authenticated user --}}
@jsmodel('Auth::user()')

{{-- Custom variable name --}}
@jsmodel('Auth::user()', 'currentUser')

{{-- Method chains --}}
@jsmodel('Auth::user()->profile()', 'userProfile')

{{-- Static property --}}
@jsmodel('App\Models\Setting::$defaults', 'appDefaults')

Output:

<script>
currentUser = {"id":1,"name":"Alice","email":"[e-mail]"};
</script>

Bind any variable from PHP

You can also pass variables directly using the facade:

// In a controller or view composer
$script = JSLocalization::get('messages', 'errors');    // returns <script>...</script>
$script = JSLocalization::put($collection, 'myData');   // serialize a collection
echo $script;

API Reference

JSLocalization::get()

JSLocalization::get(
    string $langfile,       // Language file name (without .php extension)
    string $group   = '',   // Optional key within the file to expose
    string $basevar = ''    // JS global variable (default: config 'default_base_var')
): string

Returns a <script> tag that assigns the translation array to window.{basevar}.{langfile}.

JSLocalization::put()

JSLocalization::put(
    mixed  $model,          // Eloquent model, collection, array, or object
    string $variable = ''   // JS variable name (default: class basename)
): string

Returns a <script> tag that assigns the JSON-encoded value to a global variable.

Blade directive — @jslocalization

@jslocalization(string $langfile, string $group = '', string $basevar = '')

Blade directive — @jsmodel

@jsmodel(string $expression, string $variable = '')

$expression can be:

• A static method call: 'Auth::user()'
• A method chain: 'Auth::user()->roles()'
• A static property: 'App\Models\Config::$defaults'

License

The MIT License (MIT). See LICENSE.