Download the PHP package genl/matice without Composer

Use your Laravel translations in JavaScript

https://github.com/genl/matice/actions/workflows/.github/workflows/tests.yml/badge.svg?event=push

Matice creates a Blade directive that you can include in your views. It will export a JavaScript object of your Laravel application's translations, keyed by their names (aliases, lang, filenames, folders name), as well as globals trans(), __() and transChoice() helper functions which you can use to access your translations in your JavaScript.

• Installation
• Usage
  • Examples
  • trans
  • Update locale
  • Pluralization
  • Trans Choice
  • underscore function
  • Default Values
  • Retrieve the current locale
  • Force locale
• Filtering translations
  • Filtering namespaces
• Use with SPA
• Using with Vue Components
• Dive Deeper

Installation

You can install the package via composer:

1. Include our Blade directive (@translations) somewhere in your template before your main application JavaScript is loaded—likely in the header somewhere.

2. Publish the vendor if you want to customize config:

Matice is available as an NPM matice package which exposes the trans() function for use in frontend applications that do not use Blade. You can install the NPM package with:

or load it from a CDN:

• Note that the JavaScript package only contains the translations logic. You have to generate your translations file and make it available to your frontend app. The blade directive @translations will do it for you anytime you reload the page.

TypeScript support

Matice is fully written in TypeScript so, it's compatible with TypeScript projects.

Usage

• Core concepts

Matice comes with almost the same localization concepts as Laravel. Read more about Laravel localization

This package uses the @translations directive to inject a JavaScript object containing all of your application's translations, keyed by their names. This collection is available globally on the client side in the window.Matice object. The @translations directive accepts a list of locales to be loaded under th form of an array or a comma seperated string. If no locales are given, all the translations will be loaded.

Examples

import the trans() function like follow:

The package also creates an optional trans() JavaScript helper which works like Laravel's PHP trans() helper to retrieve translation strings.

Examples

import the trans() function like follow:

Let's assume we have this translations file:

trans

Retrieve a text:

Update locale

Matice exposes setLocale function to change the locale that is used by the trans function.

Pluralization

On pluralization, the choice depends on the count argument. To activate pluralization pass the argument pluralize to true.

Trans Choice

Matice provides a helper function for pluralization

Underscore function

• As well of the trans() function, Matice provide __() that does the same as the trans() function but with this particularity not to throw an error when the key is not found but returns the key itself.

transChoice() always throws an error if the key is not found. To change this behaviour, use __(key, {pluralize: true})

Default values

Matice uses your current app locale app()->getLocale() as the default locale when generating the translation object with the blade directive @translations. Same applies when generating with command line.

When Matice does not find a key, it falls back to the default locale and search again. The fallback is the same you define in your config.app.fallback_locale.

Retrieve the current locale

Matice exposes the MaticeLocalizationConfig class :

Matice also provides helpers to deal with locales information:

Force locale

With the version 1.1.4, it is possible to force the locale for a specific translation WITHOUT changing the global local.

Filtering translations

Matice supports filtering the translations it makes available to your JavaScript, which is great to control the size of your data your translations become too large with thousands of lines.

Filtering namespaces

To set up namespace translations filtering, update in your config file either an only or except setting as an array of translations folders or files. Note: Setting the same namespace both 'only' and 'except' will result to 'except'. But in the other cases, 'only' takes precedence over 'except'

The base directory is the lang_directory defined in the config file: config('matice.lang_directory').

Use with SPA

Matice registers an Artisan console command to generate a matice_translations.js translations file, which can be used (or not) as part of an asset pipeline such as Laravel Mix.

You can run php artisan matice:generate --no-export in your project to generate a static translations file without the export statement in resources/assets/js/matice_translations.js. You can customize the generation path in the config/matice.php file.

An example of matice_translations.js, where auth translations exist in resources/lang/en/auth.php:

At this point you can use in javascript this translations file like usual, paste in your html as well.

This is useful if your laravel and js app are separated like with SPA or PWA. So you can link the generated translations file with your JS App. If you're not in the case of SPA, WPA... you might never have to generate the translations manually because @translations directive already does it for you when the app environment is 'production' to improve performance.

Whenever your translation messages change, run php artisan matice:generate again. Remember to disable browser cache, it may have cached the old translations file.

Using with Vue Components

Basically, Matice can be integrated to any Javascript projects. Event with some big framework like Vue.js React.js or Angular. Some frameworks like Vue re-renders the UI dynamically. In this section we show you how to bind Matice with Vue 2. Based on this example we assume you can take inspiration to do the same with the framework you use for your project. For example, with React, you should re-render the whole app after setLocale() is called for the changes to be visible.

Add this to your app.js file:

Then you can use the methods in your Vue components like so:

Dive Deeper

Matice extends the Laravel Translator class. Use Translator::list() to return an array representation of all of your app translations.

If you want to load only translations of a specific locale, use the matice facade:

Environment-based loading of minified matice helper file

When using the @translations Blade directive, Matice detects the current environment and minify the output if APP_ENV is production.

In development, @translations loops into the lang directory to generate the matice object each time the page reloads, and doesn't generatematice_translations.js file. In production, @translations generate the matice_translations.js file for you when your app is open for the first time then the generated file is used every time the page reloads. The Matice object is not generated every time, so it has no effect on performances in production. This behavior can be disabled in the config/matice.php file, set use_generated_translations_file_in_prod to false.

Note: Matice supports json translation files as well as php files.,

Testing

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• GENL
• All Contributors
• This package was largely inspired by Ziggy

License

The MIT License (MIT). Please see License File for more information.

Laravel Package Boilerplate

This package was generated using the Laravel Package Boilerplate.