Laravel Lang Bundler
, (*1)
Make bundles of translation values.
Contents
Why
Why use this package? Because this sucks:, (*2)
<component
welcome={{ trans('home.welcome') }}
login={{ trans('home.login') }}
signup={{ trans('home.signup') }}
profile={{ trans('user.settings.profile') }}
friends={{ trans('user.home.friends') }}
intro={{ trans('user.home.intro') }}
body={{ trans('user.home.body') }}
></component>
And this is so much better:, (*3)
<component
:lang={{ transB('bundle_name')->toJson() }}
></component>
Version 1.0.* to Version 1.1.*
Version 1.1.0 drops support for PHP versions lower than 7.1., (*4)
Version 0.9.* to Version 1.0.0
Version 1.0.0 is more a confimation of the current api and usage than anything else. Adds support for Laravel 5.4. If using Laravel 5.3, please use Version 0.9.11:, (*5)
composer require zachleigh/laravel-lang-bundler:0.9.*
Install
1. Install through composer
composer require zachleigh/laravel-lang-bundler
2. Register the service provider
In Laravel's config/app.php file, add the service provider to the array with the 'providers' key., (*6)
LaravelLangBundler\ServiceProvider::class
3. Publish the config file:
php artisan vendor:publish --tag=config
4. Create a 'bundles' directory in resources/lang/.
Do it manually or use the command:, (*7)
php artisan langb:start
Usage
1. Make a bundle.
Imagine we have two lang files, one called 'home.php' and one called 'user.php'., (*8)
home.php, (*9)
'welcome' => 'Welcome!',
'login' => 'Login',
'signup' => 'Signup',
user.php, (*10)
'profile' => 'Your Profile',
'friends' => 'Your Friends',
'body' => 'Enter body below',
We want all of these values in one bundle., (*11)
Simply register your bundle as an array anywhere in the bundles directory. For example, in the bundles directory, you could create a folder called 'components' and in it a file called 'bundle_name' that looks like this:, (*12)
return [
'home.welcome',
'home.login',
'home.signup',
'user.profile',
'user.friends',
'user.body'
];
Obviously, 'bundle_name' is the name of the bundle. The other values represent keys found in the above lang files., (*13)
Like in other lang folders, any file/folder in the bundles directory is treated as a level in an array. So in the above example, our file path looks like this:, (*14)
lang/bundles/components/bundle_name.php, (*15)
The path for the 'bundle_name' bundle would be 'bundles.components.bundle_name'. It is also possible to create multiple named bundles within a single file, but this is not recommended because you can not use auto-aliasing for multi-bundle files., (*16)
2. Get the bundle using the transB() helper function.
Get your translated bundle by passing the bundle path to the transB() helper function., (*17)
transB('bundles.components.bundle_name');
Or use the auto-aliased name:, (*18)
transB('bundle_name');
transB() returns a collection of translated values keyed by the original translation key. Continuing the example above, transB() would give us a collection that contains the following array:, (*19)
[
'welcome' => 'Welcome!',
'login' => 'Login',
'signup' => 'Signup',
'profile' => 'Your Profile',
'friends' => 'Your Friends',
'body' => 'Enter body below',
];
3. Pass parameters to your bundle.
Like with the standard trans() function, you may pass parameters to the transB() function as the second argument., (*20)
transB('bundle_name', ['parameterName' => $value]);
If your bundle has conflicting parameter names, you can namespace them. In this example, three values require a user
parameter., (*21)
user.php translation file:, (*22)
return [
'welcome_user' => 'Welcome :user',
'message_to' => 'You sent a message to :user',
'invite_from' => 'You have an invite from :user'
];
Bundle file:, (*23)
return [
'user.welcome_user',
'user.message_to',
'user.invite_from'
];
Avoid the naming conflict by namespacing the parameters when passing them to transB():, (*24)
transB('bundle_name', [
'welcome_user.user' => 'Bob',
'message_to.user' => 'Sally',
'invite_from.user' => 'George'
]);
4. Pluralize values
It is possible to pluralize lang items by passing a namespaced 'choice' parameter in the transB() function parameters. For example, if our lang file value looked like this:, (*25)
'inbox_status' => 'You have a new message.|You have new messages'
We could register it in our bundle normally:, (*26)
'home.inbox_status'
And then when calling transB(), pass a parameter called 'inbox_status.choice' with the desired choice value:, (*27)
transB('bundle_name', ['inbox_status.choice' => 3]);
The result will look be the pluralized string "You have new messages"., (*28)
Advanced Usage
Modify return keys and values
To modify the key and value in the returned translation array, use the bundle_item() helper on a specific bundle item., (*29)
bundle_item($id, $type, $parameters = []);
$id is the lang key. $type must be in the following format: 'target_type'. 'target' declares what item is to be affected by the modification and can be set to either 'value', 'key', or 'both'. 'type' declares the type of modification (callback, change etc.). $parameters is an array of parameters to be sent to the class that performs the modification., (*30)
If using the same example as above we wanted to convert the 'welcome_user' value to all caps, we could accomplish it by using the bundle_item() helper function in the bundle file.
user.php translation file:, (*31)
return [
'welcome_user' => 'Welcome :user',
'message_to' => 'You sent a message to :user',
'invite_from' => 'You have an invite from :user'
];
Bundle file:, (*32)
return [
bundle_item('user.welcome_user', 'value_strtoupper'),
'user.message_to',
'user.invite_from'
];
Wrap the bundle key 'user.welcome_user' in the bundle_item() global function and pass the translation key ($id) plus the type (perform a 'strtoupper' on the returned 'value'). This returns the following values (assuming a non-namespaced user variable with the value 'Bob'):, (*33)
[
'welcome_user' => 'WELCOME BOB',
'message_to' => 'You sent a message to Bob',
'invite_from' => 'You have an invite from Bob'
];
If we wanted to do the same to the key, we could do this:, (*34)
return [
bundle_item('user.welcome_user', 'key_strtoupper'),
'user.message_to',
'user.invite_from'
];
Or, if we wanted to perform the modification on both the key and the value:, (*35)
return [
bundle_item('user.welcome_user', 'both_strtoupper'),
'user.message_to',
'user.invite_from'
];
Available modifiers
callback
Perform a callback on a key or value. Requires a 'callback' parameter., (*36)
bundle_item('user.welcome_user', 'value_callback', [
'callback' => 'function_name'
]),
change
Change a key to a new value. Does nothing to values. Requires 'new' parameter., (*37)
bundle_item('user.invite_from', 'key_change', [
'new' => 'newKey'
]),
explode
Explode by given delimiter. Does nothing to key. Requires 'delimiter' parameter., (*38)
bundle_item('user.invite_from', 'value_explode', [
'delimiter' => ' '
]),
strtolower
Lowercase entrire string., (*39)
bundle_item('home.invite_from', 'value_strtolower')
strtoupper
Capitalize entire string., (*40)
bundle_item('home.invite_from', 'value_strtoupper')
ucfirst
Make first character in string capitalized., (*41)
bundle_item('home.invite_from', 'value_ucfirst')
values
If translation value is an array, run array_values() on array and return only values keyed by integers. Does nothing to keys., (*42)
bundle_item('home.months', 'value_values')
Creating your own modifier
Use the 'mod' command to create a new mod class in App/LangBundler/Mods:, (*43)
langb:mod {name}
There are two abstract methods that must be implemented in your class:, (*44)
/**
* Alter key and return.
*
* @param string $key
*
* @return string
*/
abstract public function key($key);
/**
* Alter value and return.
*
* @param mixed $value
*
* @return mixed
*/
abstract public function value($value);
The same class is used to modify both the value and key. Define your modification and return the desired key/value., (*45)
Commands
php artisan langb:start
Get started by creating a bundles directory in your lang folder., (*46)
php artisan langb:new {path}
Create a new bundle file located at path. For example:, (*47)
php artisan langb:new components.user.profile
This would create the file lang/bundles/components/user/profile.php with an empty returned array., (*48)
php artisan langb:mod {name}
Create an empty mod template in App/LangBundler/Mods., (*49)
Configuration
aliases
To shorten the name of bundles, you can register aliases in config., (*50)
'aliases' [
'alias' => 'full.path.to.bundle'
];
And then simply use the alias istead of the path in transB():, (*51)
transB('alias');
If you wish to transform lang file keys to snake_case, StudlyCase, or camelCase, set key_transform
to 'snake_case', 'studly_case', or 'camel_case'. Default value is 'none'.
For example, this bundle contains snake cased variables:, (*52)
return [
'user.welcome_user',
'user.message_to',
'user.invite_from'
];
But in your javascript, you want to use came cased variables, set key_transform
to 'camel_case' to get this bundle:, (*53)
return [
'welcomeUser' => 'Welcome user!',
'messageTo' => 'Message to user',
'inviteFrom' => 'You have an invitation from user!',
];
Many other simple string functions (ucfirst, strtoupper, etc.) also work., (*54)
key_transform is global and will transform all keys in your project. If you wish to transform a single key, see modify return keys and values., (*55)
global_key_namespace
If you keep all your translations in a single file, you can set global_key_namespace
to the name of the file to save yourself some typing. For example, if all your translations are in a file called 'translations.php', you would have to register a bundle like this:, (*56)
return [
'bundle_name' => [
'translations.home',
'translations.navigation',
'translations.menu',
'translations.login'
];
];
However, if you set global_key_namespace
to 'translations', you could register it like this:, (*57)
return [
'bundle_name' => [
'home',
'navigation',
'menu',
'login'
];
];
Testing
composer test
Contributing
Contributions are more than welcome. Fork, improve and make a pull request. For bugs, ideas for improvement or other, please create an issue., (*58)