{"id":15365947,"url":"https://github.com/andywer/laravel-js-localization","last_synced_at":"2025-04-04T07:06:42.781Z","repository":{"id":11233027,"uuid":"13626535","full_name":"andywer/laravel-js-localization","owner":"andywer","description":"Simple, ease-to-use and flexible package for the Laravel web framework. Allows you to use localized messages of the Laravel webapp (see `resources/lang` directory) in your Javascript code.","archived":false,"fork":false,"pushed_at":"2023-06-23T12:59:44.000Z","size":287,"stargazers_count":144,"open_issues_count":10,"forks_count":51,"subscribers_count":4,"default_branch":"laravel-8","last_synced_at":"2025-03-12T21:03:47.955Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andywer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-10-16T17:46:40.000Z","updated_at":"2025-03-12T08:59:51.000Z","dependencies_parsed_at":"2024-06-18T12:53:11.880Z","dependency_job_id":"9bd3bba4-a81c-493d-b1e9-f336fb2d912f","html_url":"https://github.com/andywer/laravel-js-localization","commit_stats":{"total_commits":163,"total_committers":22,"mean_commits":7.409090909090909,"dds":"0.33742331288343563","last_synced_commit":"33cda9e64e51443876086cdaefd8e0fe1d19678d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Flaravel-js-localization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Flaravel-js-localization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Flaravel-js-localization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Flaravel-js-localization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andywer","download_url":"https://codeload.github.com/andywer/laravel-js-localization/tar.gz/refs/heads/laravel-8","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243293792,"owners_count":20268141,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T13:16:45.988Z","updated_at":"2025-03-12T22:07:36.711Z","avatar_url":"https://github.com/andywer.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"laravel-js-localization\n=======================\n[![Build Status](https://travis-ci.org/andywer/laravel-js-localization.svg?branch=laravel-5)](https://travis-ci.org/andywer/laravel-js-localization) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/andywer/laravel-js-localization/badges/quality-score.png?b=laravel-5)](https://scrutinizer-ci.com/g/andywer/laravel-js-localization/?branch=laravel-5) [![Code Coverage](https://scrutinizer-ci.com/g/andywer/laravel-js-localization/badges/coverage.png?b=laravel-5)](https://scrutinizer-ci.com/g/andywer/laravel-js-localization/?branch=laravel-5) [![Total Downloads](https://poser.pugx.org/andywer/js-localization/downloads.svg)](https://packagist.org/packages/andywer/js-localization)\n\n\nSimple, ease-to-use and flexible package for the [Laravel](http://laravel.com/) web framework. Allows you to use localized messages of the Laravel webapp (see `resources/lang` directory) in your Javascript code. You may easily configure which messages you need to export.\n\n**⚠️ Looking for a new maintainer. Please contact me if you are interested.**\n\n\nBranches\n--------\n\n  Laravel  | Branch\n:----------|:-------\n 8         | laravel-8\n 7         | laravel-7\n 6         | laravel-6\n 5.8       | laravel-5.8\n 5.0 - 5.7 | laravel-5 (end of life)\n\n\nInstallation\n------------\n\nAdd the following line to the `require` section of your Laravel webapp's `composer.json` file:\n\n```javascript\n    \"require\": {\n        \"andywer/js-localization\": \"dev-laravel-6\"      // see table above\n    }\n```\n\n\nRun `composer update` to install the package.\n\n\nFinally add the following line to the `providers` array of your `app/config/app.php` file:\n\n```php\n    'providers' =\u003e [\n        /* ... */\n        JsLocalization\\JsLocalizationServiceProvider::class\n    ]\n```\n\n\nConfiguration\n-------------\n\nRun `php artisan vendor:publish` first. This command copies the package's default configuration to `config/js-localization.php`.\n\nYou may now edit this file to define the messages you need in your Javascript code. Just edit the `messages` array in the config file.\n\nExample (exports all reminder messages):\n\n```php\n\u003c?php\n\nreturn [\n    // Set the locales you use\n    'locales' =\u003e ['en'],\n\n    // Set the keys of the messages you want to use in javascript\n    'messages' =\u003e [\n        'passwords' =\u003e [\n            'password', 'user', 'token'\n        ]\n    ],\n\n    /*\n     * in short:\n     * 'messages' =\u003e ['passwords']\n     *\n     *\n     * you could also use:\n     *\n     * 'messages' =\u003e [\n     *     'passwords.password',\n     *     'passwords.user',\n     *     'passwords.token'\n     * ]\n     */\n     \n    // Set the keys of config properties you want to use in javascript.\n    // Caution: Do not expose any configuration values that should be kept privately!\n    'config' =\u003e [\n        'app.debug'\n    ],\n     \n    // Disables the config cache if set to true, so you don't have to run `php artisan js-localization:refresh`\n    // each time you change configuration files.\n    // Attention: Should not be used in production mode due to decreased performance.\n    'disable_config_cache' =\u003e false,\n\n    // Split up the exported messages.js file into separate files for each locale.\n    // This is to ensue faster loading times so one doesn't have to load translations for _all_ languages.\n    'split_export_files' =\u003e true,\n];\n```\n\n__Important:__\n\nThe messages configuration will be cached when the JsLocalizationController is used for the first time. After changing the messages configuration you will need to call __`php artisan js-localization:refresh`__ to refresh that cache. That also affects the config properties you export to javascript, since they are cached, too.\n\n\nUsage\n-----\n\nThe translation resources for JavaScript can either be served by your Laravel app at run-time or they can be pre-generated as static JavaScript files, allowing you to serve them straight from your web server or CDN or to be included in your build process.\n\n### Run-time generation\n\nYou just need to add the necessary `\u003cscript\u003e` tags to your layout. Here is an example blade view:\n\n```html\n@include('js-localization::head')\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n    \u003chead\u003e\n        \u003ctitle\u003eTest view\u003c/title\u003e\n        @yield('js-localization.head')\n    \u003c/head\u003e\n    \u003cbody\u003e\n        \u003cp\u003e\n            Here comes a translated message:\n            \u003cscript type=\"text/javascript\"\u003e\n                document.write( Lang.get('reminder.user') );\n            \u003c/script\u003e\n        \u003c/p\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\nRemember it's best to not put the `@yield('js-localization.head')` in the `\u003chead\u003e` as it contains the `\u003cscript\u003e` tag\nshipping the frontend part of this package. It's best practice to put it at the end of the `\u003cbody\u003e`, but **before**\nother `\u003cscript\u003e` tags. The example above simply includes it in the head, since it's the simplest form to use it. \n\n### Static generation\n\nFor increased performance it is possible to generate static JavaScript files with all of your generated strings. These files can either be served directly as static files, or included as a part of your frontend asset build process.\n\nTo specify the output directory for the assets, just set the `$storage_path` string in your `config/js-localization.php` file accordingly (see [Configuration](#configuration)).\n\n```\n    /*\n    |--------------------------------------------------------------------------\n    | Define the target to save the exported messages to\n    |--------------------------------------------------------------------------\n    |\n    | Directory for storing the static files generated when using file storage.\n    |\n    */\n\n    'storage_path' =\u003e public_path('vendor/js-localization/'),\n```\n\nThe files can then be generated using the artisan command:\n\n`php artisan js-localization:export`\n\nThis will generate two files in your target directory:\n * `messages.js` contains your translation strings\n * `config.js` contains your exported config values\n\nIf you want to automatically split up the `messages.js` file into separate .js files for each locale, you can set the following to true in your `config/js-localization.php` config file:\n\n```\n    'split_export_files' =\u003e true,\n```\n\nThis will in turn _also_ generate the following file(s) in your target directory:\n * `lang-{locale}.js` contains one language's translation strings, if the `split_export_files` config option is set to true\n\nRemember that the files needs to be regenerated using `php artisan js-localization:export` every time any translation strings are edited, added or removed.\n\nFeatures\n--------\n\nYou may use Lang.get(), Lang.has(), Lang.choice(), Lang.locale() and trans() (alias for Lang.get()) in your Javascript code. They work just like Laravel's `Lang` facade.\nAdditionally, you are able to pass configuration properties to your Javascript code as well. There is Config.get() in Javascript, too. Configure which config properties to pass to the client using the `config` field in `config/js-localization.php`. Attention: Do not export any security-critical properties like DB credentials or similar, since they would be visible to anyone using your application!\n\nVariables in messages are supported. For instance: `\"This is my test string for :name.\"`.\n\nPluralization is also supported, but does not care about the locale. It only uses the English pluralization rule (`\"singular text|plural text\"`). More complex pluralization quantifiers are not yet supported.\n\n\nService providers\n-----------------\n\nAssume you are developing a laravel package that depends on this javascript localization features and you want to configure which messages of your package have to be visible to the JS code.\n\nFortunately that's pretty easy. Just listen to the `JsLocalization.registerMessages` event and use the `JsLocalization\\Facades\\JsLocalizationHelper::addMessagesToExport()` method. Like so:\n\n```php\n\u003c?php\n\nuse Illuminate\\Support\\ServiceProvider;\nuse JsLocalization\\Facades\\JsLocalizationHelper;\n\nclass MyServiceProvider extends ServiceProvider\n{\n    /* ... */\n\n    public function register()\n    {\n        Event::listen('JsLocalization.registerMessages', function()\n        {\n            JsLocalizationHelper::addMessagesToExport([\n                // list the keys of the messages here, similar\n                // to the 'messages' array in the config file\n            ]);\n        });\n    }\n\n    /* ... */\n}\n```\n\n\nLicense\n-------\n\nThis software is released under the MIT license. See [license](https://raw.github.com/andywer/laravel-js-localization/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandywer%2Flaravel-js-localization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandywer%2Flaravel-js-localization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandywer%2Flaravel-js-localization/lists"}