Download the PHP package zachleigh/laravel-lang-bundler without Composer

Laravel Lang Bundler

Make bundles of translation values.

Contents

• Why
• Upgrade Information
• Install
• Usage
• Advanced Usage
• Commands
• Configuration
• Limitations
• Testing
• Contributing

Why

Why use this package? Because this sucks:

And this is so much better:

Upgrade Information

Version 1.0. to Version 1.1.

Version 1.1.0 drops support for PHP versions lower than 7.1.

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:

Install

1. Install through composer

2. Register the service provider

In Laravel's config/app.php file, add the service provider to the array with the 'providers' key.

3. Publish the config file:

4. Create a 'bundles' directory in resources/lang/.

Do it manually or use the command:

Usage

1. Make a bundle.

Imagine we have two lang files, one called 'home.php' and one called 'user.php'.

home.php

user.php

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:

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.

2. Get the bundle using the transB() helper function.

Get your translated bundle by passing the bundle path to the transB() helper function.

Or use the auto-aliased 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:

3. Pass parameters to your bundle.

Like with the standard trans() function, you may pass parameters to the transB() function as the second argument.

If your bundle has conflicting parameter names, you can namespace them. In this example, three values require a user parameter.

user.php translation file:

Bundle file:

Avoid the naming conflict by namespacing the parameters when passing them to transB():

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:

We could register it in our bundle normally:

And then when calling transB(), pass a parameter called 'inbox_status.choice' with the desired choice value:

The result will look be the pluralized string "You have new messages".

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.

$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:

Bundle file:

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'):

If we wanted to do the same to the key, we could do this:

Or, if we wanted to perform the modification on both the key and the value:

Available modifiers

callback

Perform a callback on a key or value. Requires a 'callback' parameter.

change

Change a key to a new value. Does nothing to values. Requires 'new' parameter.

explode

Explode by given delimiter. Does nothing to key. Requires 'delimiter' parameter.

strtolower

Lowercase entrire string.

strtoupper

Capitalize entire string.

ucfirst

Make first character in string capitalized.

values

If translation value is an array, run array_values() on array and return only values keyed by integers. Does nothing to keys.

Creating your own modifier

Use the 'mod' command to create a new mod class in App/LangBundler/Mods:

There are two abstract methods that must be implemented in your class:

The same class is used to modify both the value and key. Define your modification and return the desired key/value.

Commands

php artisan langb:start

Get started by creating a bundles directory in your lang folder.

php artisan langb:new {path}

Create a new bundle file located at path. For example:

This would create the file lang/bundles/components/user/profile.php with an empty returned array.

php artisan langb:mod {name}

Create an empty mod template in App/LangBundler/Mods.

Configuration

aliases

To shorten the name of bundles, you can register aliases in config.

And then simply use the alias istead of the path in transB():

key_transform

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:

But in your javascript, you want to use came cased variables, set key_transform to 'camel_case' to get this bundle:

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.

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:

However, if you set global_key_namespace to 'translations', you could register it like this:

Testing

Contributing

Contributions are more than welcome. Fork, improve and make a pull request. For bugs, ideas for improvement or other, please create an issue.