README

Using the Localization feature of Laravel 5, especially for a multilingual application, can be frustrating and time consuming to work simultaneously on the view and locale files. If the application is quite complicated and designated to support a number of locales, building the structure of the locale files is tedious. When it's necessary to modify improperly declared locale key names, or to move locale lines from one file to another, or to maintain well structured nested locale arrays, it's not just painful, but can cause troubles sometimes.

In addition to the build-in Localization function of Laravel, installing third-party packages, such as drewneon/lang4js, spatie/laravel-translatable and ARCANEDEV/Localization, does arm an application to teeth in terms of the completion of multilingualism. However, the syntax of json datatype can be a headache, especially when there are quite several supported locales and the language strings are as long as multipage blog articles.

Moreover, it shouldn't be the developer's obligation to translate a website, and qualified translators are very unlikely familiar with PHP codes nor database stuff. In short, even with the good foundation structured by Laravel and improvements made by various great packages, there is still a big gap to complete a multilingual application. And this is where TransUI fills in.

Features

Automatically creates locale folders for supported locales if missing, no need to manually create them when adding new supported locals;
Highlights missing folders and files for default locale in Dir Tree and missing entries for any locale in Entry Table, and automatically create necessary folders and files when save changes;
Displays detailed stats and translation progress dynamically;
Allows to delete unused translation strings;
Allows to modify key names if necessary and updates all views concerned automatically when save changes;
Integrates drewneon/lang4js making this package fully multilingual;
Supports various third-party localization or i18N packages, such as ARCANEDEV/Localization, via config settings;
Supports spatie/laravel-translatable for translations of database entries.

![alt tag] (screenshot.jpg)

Compatibility

The current version of TransUI is developed on Laravel 5.3 and briefly tested on 5.4. Any previous versions of Laravel greater than 4.2 are supposed to be compatible. If not, please raise an issue or help to contribute.

In order to utilize TransUI's feature of supporting spatie/laravel-translatable, please refer to the its docs for Laravel version compatibility.

Install

1) Via Composer

$ composer require drewneon/transui

This will also install drewneon/lang4js packages as an dependency.

2) Then add the service providers in config/app.php

'providers' => [
    ...
    DrewNeon\Lang4JS\Lang4JSServiceProvider::class,
    DrewNeon\TransUI\TransUIServiceProvider::class,

];

3) And publish the asset files with the following two commands

$ php artisan vendor:publish --provider="DrewNeon\TransUI\TransUIServiceProvider"
$ php artisan vendor:publish --tag=public --force

4) Finally, add routes to routes/web.php

Route::post('/lang4js', '\DrewNeon\Lang4JS\Lang4JSController@lang4js');
Route::group(['prefix' => config('transui.route_name'), 'as' => 'TransUI', 'middleware' => 'web'], function () {
    Route::get('/',  ['as' => 'get',  'uses' => '\DrewNeon\TransUI\TransUIController@index']);
    Route::post('/', ['as' => 'post', 'uses' => '\DrewNeon\TransUI\TransUIController@save']);

});

Configuration

In order to take the full advantage of TransUI, please take a look at the docs of drewneon/lang4js and spatie/laravel-translatable first.

The published config file of TransUI is located at /config/transui.php. TransUI is supposed to work with the default settings pre-configed there. Please make necessary changes according to the comments for each setting in that file.

In addition to these custom configurations, TransUI refers to the fallback_locale setting in /config/app.php as the default locale. TransUI assumes that this default locale already exists in the application, i.e. there is a folder with this locale name containing locale files under /resources/lang, otherwise it'll end up with an error message when loading TransUI.

Usage

Before starting to use TransUI, please examine the syntax of all the existing locale files first.

DO NOT name the locale file with dot, for example, some_locale_file.php is good, but some.locale.file.php is NOT!
Each locale string MUST ends with ,\n, i.e. comma and enter, even for nested arrays. DO NOT omit the last comma for an array. DO NOT write nested arrays in one line, there MUST be \n after each [ and ],.

Now please visit http://yourdomain.com/TransUI or the custom URL set in the config file to enjoy TransUI. The web interface of TransUI is quite self-explanatory. It's a bit tricky only when the key name is needed to be modified. The key name field must be double clicked to activate modification, instead of single click.

The recommended steps of adding new strings, as well as new locale files, is

write something like trans('whatever_locale_folder/whatever_locale_file.whatever_locale_key_name') directly in any view blade,
save the blade,
then open TransUI in a browser, there will be an item marked as missing referring to what was written in step 1,
locate this missing item,
type in appropriate content in the default locale column of this missing item row,
blur the input,
click the save button.

Helpers

TransUI provides several useful helpers as a bonus.

1) nativeLangName($lang_code)

It translates the standard locale code into the name of the language in its native language, for example, nativeLangName('en') returns 'English', nativeLangName('ko') returns '한국어', and etc.

2) ksortDeep($nested_array)

It sorts all levels of nested arrays to alphabetic order.

3) textBetween($string, $start, $end)

It retrieves text between $start and $end in $string, for example

textBetween('the gray fox jumped over the lazy dog', 'gray', 'over');

return ' fox jumped '

4) filterFilesByExtention($array, $extension)

It filters an array of file names with full path and returns those match $extension as an array.

Todo

The next release of TransUI will have a web interface for all the config settings and better support for Laravel 5.4.

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email :author_email instead of using the issue tracker.

Credits

License

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

drewneon / transui

Maintainers

Details