- Why
- Upgrade Information
- Install
- Usage
- Advanced Usage
- Commands
- Configuration
- Limitations
- Testing
- Contributing
Why use this package? Because this sucks:
<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:
<component
:lang={{ transB('bundle_name')->toJson() }}
></component>Version 1.1.0 drops support for PHP versions lower than 7.1.
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:
composer require zachleigh/laravel-lang-bundler:0.9.*
composer require zachleigh/laravel-lang-bundler
In Laravel's config/app.php file, add the service provider to the array with the 'providers' key.
LaravelLangBundler\ServiceProvider::class
php artisan vendor:publish --tag=config
Do it manually or use the command:
php artisan langb:start
Imagine we have two lang files, one called 'home.php' and one called 'user.php'.
home.php
'welcome' => 'Welcome!',
'login' => 'Login',
'signup' => 'Signup',user.php
'profile' => 'Your Profile',
'friends' => 'Your Friends',
'body' => 'Enter body below',We want all of these values in one bundle.
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:
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.
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:
lang/bundles/components/bundle_name.php
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.
Get your translated bundle by passing the bundle path to the transB() helper function.
transB('bundles.components.bundle_name');Or use the auto-aliased name:
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:
[
'welcome' => 'Welcome!',
'login' => 'Login',
'signup' => 'Signup',
'profile' => 'Your Profile',
'friends' => 'Your Friends',
'body' => 'Enter body below',
];Like with the standard trans() function, you may pass parameters to the transB() function as the second argument.
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.
user.php translation file:
return [
'welcome_user' => 'Welcome :user',
'message_to' => 'You sent a message to :user',
'invite_from' => 'You have an invite from :user'
];Bundle file:
return [
'user.welcome_user',
'user.message_to',
'user.invite_from'
];Avoid the naming conflict by namespacing the parameters when passing them to transB():
transB('bundle_name', [
'welcome_user.user' => 'Bob',
'message_to.user' => 'Sally',
'invite_from.user' => 'George'
]);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:
'inbox_status' => 'You have a new message.|You have new messages'We could register it in our bundle normally:
'home.inbox_status'And then when calling transB(), pass a parameter called 'inbox_status.choice' with the desired choice value:
transB('bundle_name', ['inbox_status.choice' => 3]);The result will look be the pluralized string "You have new messages".
To modify the key and value in the returned translation array, use the bundle_item() helper on a specific bundle item.
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.
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:
return [
'welcome_user' => 'Welcome :user',
'message_to' => 'You sent a message to :user',
'invite_from' => 'You have an invite from :user'
];Bundle file:
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'):
[
'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:
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:
return [
bundle_item('user.welcome_user', 'both_strtoupper'),
'user.message_to',
'user.invite_from'
];Perform a callback on a key or value. Requires a 'callback' parameter.
bundle_item('user.welcome_user', 'value_callback', [
'callback' => 'function_name'
]),Change a key to a new value. Does nothing to values. Requires 'new' parameter.
bundle_item('user.invite_from', 'key_change', [
'new' => 'newKey'
]),Explode by given delimiter. Does nothing to key. Requires 'delimiter' parameter.
bundle_item('user.invite_from', 'value_explode', [
'delimiter' => ' '
]),Lowercase entrire string.
bundle_item('home.invite_from', 'value_strtolower')Capitalize entire string.
bundle_item('home.invite_from', 'value_strtoupper')Make first character in string capitalized.
bundle_item('home.invite_from', 'value_ucfirst')If translation value is an array, run array_values() on array and return only values keyed by integers. Does nothing to keys.
bundle_item('home.months', 'value_values')Use the 'mod' command to create a new mod class in App/LangBundler/Mods:
langb:mod {name}
There are two abstract methods that must be implemented in your class:
/**
* 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.
Get started by creating a bundles directory in your lang folder.
Create a new bundle file located at path. For example:
php artisan langb:new components.user.profile
This would create the file lang/bundles/components/user/profile.php with an empty returned array.
Create an empty mod template in App/LangBundler/Mods.
To shorten the name of bundles, you can register aliases in config.
'aliases' [
'alias' => 'full.path.to.bundle'
];And then simply use the alias istead of the path in transB():
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:
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:
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.
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.
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:
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:
return [
'bundle_name' => [
'home',
'navigation',
'menu',
'login'
];
];composer test
Contributions are more than welcome. Fork, improve and make a pull request. For bugs, ideas for improvement or other, please create an issue.