Matice creates a Blade directive that you can include in your views. It will export a JavaScript object of your 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.
You can install the package via composer:
composer require genl/maticephp artisan vendor:publish --provider=Genl\Matice\MaticeServiceProviderMatice is available as a NPM package matice
that exposes the trans() function for use in frontend apps that
are not using Blade.
You can install the NPM package with:
// With yarn
yarn add matice
With npm
npm install maticeor load it from a CDN:
<!-- Load the Matice translation object first -->
<script defer src="https://unpkg.com/matice@1.1.x/dist/matice.min.js"></script>- Note that you still have to generate your translations file and make
it available to your frontend app by using
@translations.
TypeScript support
Matice is fully written in TypeScript so, it's compatible with TypeScript projects.
Matice comes with almost the same localization concepts as Laravel does. 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 at Matice.translations.
The package also creates an optional trans() JavaScript helper that functions like Laravel's PHP trans() helper, which can be used to retrieve translation sentences.
import the trans() function like follow:
import { trans } from "matice";Let's assume we have this translations:
// resources/lang/en/custom.php
return [
'greet' => [
'me': 'Hello!',
'someone' => 'Hello :name!',
'me_more' => 'Hello Ekcel Henrich!',
'people' =>'Hello Ekcel!|Hello everyone!',
],
balance => '{0} You're broke|[1000, 5000] a middle man|[1000000,*] You are awesome :name; :count Million Dollars'
];// resources/lang/fr/custom.php
return [
'greet' => [
me => 'Bonjour!'
]
];Retrieve a text:
let sentence = ''
sentence = trans('greet.me') // Hello!
// With parameters
sentence = trans('greet.someone', {args: {name: "Ekcel"}}) // Hello Ekcel!Matice expose setLocale function to uchange the locale that is used by the trans function.
import { setLocale } from "matice"
// update the locale
setLocale('fr')
sentence = trans('greet.me') // Bonjour!Pluralization depends on the count argument.
// Pluralization
sentence = trans('greet.people', {args: {count: 0}, pluralize: true}) // Hello Ekcel!
sentence = trans('greet.people', {args: {count: 2}, pluralize: true}) // Hello everyone!
// Advanced pluralization with range
sentence = trans('balance', {args: {count: 0}, pluralize: true}) // You're broke
sentence = trans('balance', {args: {count: 3000}, pluralize: true}) // a middle manMatice provides a helper function for pluralization
import { transChoice } from "matice"
let sentence = transChoice('balance', 17433085, {name: 'Ekcel'}) // You are awesome Ekcel; 17433085 Million Dollars- As well of the
trans()function, Matice provide__()that does the same as thetrans()function but with this particularity not to throw an error when the key is not found but returns an the key itself.
transChoice() always throws an error if the key is not found. To change this behaviour, use __(key, {pluralize: true})
sentence = trans('greet.unknown') // -> throws an error with a message.
sentence = __('greet.unknown') // greet.unknownMatice uses your current app locale app()->getLocale() a the default locale when generating the translation object with the blade directive @translations.
When generating with command line, it use the one in your config.app
When Matice does not find a key, he fallback to the default locale and search again. The fallback is the same you define in your config.
// config/app.php
'locale' => 'fr',
'fallback_locale' => 'en',To locales information, matice exposes the MaticeLocalizationConfig class :
import { MaticeLocalizationConfig } from "matice"
const locale = MaticeLocalizationConfig.locale // 'en'
const fallbackLocale = MaticeLocalizationConfig.fallbackLocale // 'en'
const locales = MaticeLocalizationConfig.locales // ['en', 'fr']Matice also provides helpers to deal with locales information:
import { setLocale, getLocale, locales } from "matice"
// Update the locale
setLocale('fr') //
const locale = getLocale() // 'en'
const locales = locales() // ['en', 'fr']Matice registers an Artisan console command to generate a matice_translations.js translations file, which can be used as part of an asset pipeline such as Laravel Mix.
You can run php artisan matice:generate in your project to generate a static translations file in resources/assets/js/matice_translations.js. You can optionally include a second parameter to override the path and file name (you must pass a complete path, including the file name):
php artisan matice:generate "resources/foo.js"Example matice_translations.js, where auth translations exist in resources/lang/en/auth.php:
// resources/lang/en/auth.php
return [
'failed' => 'These credentials do not match our records.',
'throttle' => 'Too many login attempts. Please try again in :seconds seconds.',
]// matice_translations.js
const Matice = {
translations: {
en: {
auth: {
failed: 'These credentials do not match our records.',
throttle: 'Too many login attempts. Please try again in :seconds seconds.'
}
}
},
locale: 'en',
fallbackLocale: 'en'
};
export { Matice };At this point you can use javascript this translations file like usual, paste in your html as well.
If you want to use the route() helper in a Vue component, add this to your app.js file:
// app.js
import {__, trans, setLocale, getLocale, transChoice, MaticeLocalizationConfig, locales} from "matice"
Vue.mixin({
methods: {
$trans: trans,
$__: __,
$transChoice: transChoice,
$setLocale: (locale: string) => {
setLocale(locale);
app.$forceUpdate() // Refresh the vue instance after locale change.
},
// The current locale
$locale() {
return getLocale()
},
// A listing of the available locales
$locales() {
return locales()
}
},
})Then you can use the methods in your Vue components like so:
<p>{{ $trans('greet.me') }}</p>Matice extends the Laravel Translator Class. Use Translator::list() to returns
an array representation of all of your app translations.
If you want to load only translations of a specfic locale, use the matice facade:
use GENL\Matice\Facades\Matice;
// Or load translations for a specific locale.
$translations = Matice::translations($locale)
// Or all the translations
$translations = Matice::translations()Environment-based loading of minified matice helper file
When using the @translations Blade directive, Matice will detect the current environment and minify the output if APP_ENV is production.
In this case matice will run php artisan matice:generate to generate translations file (if not exists) and use it — otherwise, translations will always be re-loaded.
######Note: Matice works with json translation files as well as with php files.,
// -- laravel test --
composer test
// -- js test --
// With yarn
yarn test
// With npm
npm run testPlease see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email bigcodole@gmail.com instead of using the issue tracker.
- GENL
- All Contributors
- This package was largely inspired by Ziggy
The MIT License (MIT). Please see License File for more information.
This package was generated using the Laravel Package Boilerplate.