LARAVEL

TRANSLATOR
http://www.aesolucionesweb.com.ar/en/develope
rs/laravel-translator

Laravel Translator is the most complete and

easiest to use Laravel manager for dealing with
multiple locales and translations.
Extending Laravel's Router and URLGenerator
allows us to deal with multiple locales in Laravel's
way. And the Translator Repository allows us to
deal with translations for those locales.
It is worth to say that, if we want, we can reserve
a non-prefixed URL for our application's main
locale. Thus, from all supported locales, we
would have a clearer URL only for our main locale
(www.site.com/apple) and prefixed ones for the
rest of them (e.g., www.site.com/fr/apple).
 COMPATIBILITY
Laravel 5.*

FEATURES
Routes and urls manager.

Complete repository for translate your whole application.

Eloquent extension for translate attributes inside your models.

Schema support.

Cache optimization.

INSTALLATION
1.Adding repository files to your proyect.
The best way to install Laravel Translator is with Composer. To install the most
recent version, run the following command.

composer require aewebsolutions/laravel-

translator

2.Integration
Then, you must add two lines in config/app.php. First, add a new provider
to $providers array:

Translator\TranslatorServiceProvider::class,

Second, for a proper access to TranslatorRespository, you must add a new

facade to $aliases array:
 'Translator' =>
Translator\Facades\TranslatorFacade::class,

Optionally, if you wish to use our Schema support for an easily translatable
tables creation, you need to replace Schema facade. So, comment or remove
Laravel's and add the new one:

//'Schema' =>
Illuminate\Support\Facades\Schema::class,
'Schema' =>
Translator\Facades\Schema::class,

3.Publishing
Some files need be copied from vendor directory. Just run the following
command:

php artisan vendor:publish

--provider="Translator\TranslatorServiceProvid
er"

This command will publish next files:

app\Translation.php: an Eloquent model to deal with translations table,

database\migrations\2016_01_01_000000_create_translations_table.php:
a migration file that will create translations table,

config/translation.php: a configuration file.

4.Migration
A translations table must be created in database. Running
Artisan's migrate command would be enough. But if you need to add extra
columns to translations table,
you may do it before running command. Just add them to Schema::up in
migration file. Also, you may need to add them too to App\Translation::
$fillablearray property.
Then, run:

php artisan migrate

5.Extending Router
Add a new line to App\Http\Kernel in order to extend Laravel's Router.

class Kernel extends HttpKernel

{

use \Translator\Traits\KernelRouterExtender;
//etc.
}

CONFIGURATION
Configuration settings can be found in config/translator.php with plenty
information.For basic usage, you must add all locales supported by application
in $locales_available array. E.g., if application supports en, fr and es locales,
array will look like this:

'locales_available' => [ 'es', 'en' , 'fr' ],

Main locale takes its value from application's default locale

(see locale in config/app.php file). So, do not forget to set it correctly.

USAGE
1.Routing
1.1.Basics

This router is an extension of Laravel's, thus you will find original features
exactly like you know them.

All working routes must have at least one locale available.

 Route::get('apple', [
'locales' => 'en',
'uses' => 'fruitsController@apple'
]);

You can associate, not just a single locale, but a group of them too. Also, if you
need a route to be available for the whole group of supported locales, you can
use the all keyword.

Route::get('apple', ['locales' => ['en', 'es']

, 'uses' => 'fruitsController@apple' ]);
Route::get('peach', ['locales' => 'all' ,
'uses' => 'fruitsController@peach' ]);

Taking defaults settings, next URIs will be available in application for routes
above.

/apple

/es/apple

/peach

/es/peach

/fr/peach

Requesting any of them, current locale will be set automatically.

It is worth to say that URIs are generated dynamically in order to optimize.

Router does not have to lead with multiplied rules, but just with those that
match with requested locale. Imagine 40 route rules and 10 languages; instead
of an unnecessary route rule multiplication, you will have exactly what you
need: 40 rules.

1.2.Groups

You can assign locales to a group, not just to a single route.

Route::group([ 'locales' => 'en' , 'prefix'
=> 'fruits' ], function(){

Route::get('apple/{color}', ['locales' =>

'es', 'as' => 'apple_path', 'uses' =>
'fruitsController@apple' ]);

Route::get('peach/{color}', [ 'as' =>

'peach_path', 'uses' =>
'fruitsController@peach' ]);

});

2.URL
To get a relative or absolute URL from a route name for the current locale, as
usually, call either Laravel's route or URL::route methods:

route('apple_path', ['color' => 'red']);

If you ask for another locale, use dot notation. For getting a fallback locale's
route, pass a locale (or set true) as the four argument.

route('es.apple_path', ['color' =>

'red'] );
route('es.apple_path', ['color' => 'red'],
true, 'en' );

Also, you can get all URLs for all supported locales. Call
either Route::routes or routes new methods:

$url = routes('apple_path', ['color' => 'red']

);
echo $url->es;
echo $url->en;

Laravel's URL::current has been modified. Now, you can pass as an optional
first argument a locale.
URL::current('es');

3.Translator Repository
Laravel Translator helps you to translate your application easily, dealing with
translations from database. Translations could be managed directly
by App\Translation Eloquent model. But, you should use the provided
repository in order to guarantee stability. Translator facade, probably, is all
you need.

3.1.Getting

You can get a translated text using Translator::text method or, better,
the tthelper. This works like Laravel's trans. The tt method accepts a locale
(optionally), a group name and a needle as its first argument, using dot
notation: locale.group.needle. Let's assume that current locale is 'en':

echo tt('fruits.apple'); // output: apple

echo tt('es.fruits.apple'); // manzana

Sometimes a text may have no translation for a locale available; so, main locale
is shown. Turning false its third argument you can avoid this behavior.

echo tt('fr.fruits.apple'); // apple

echo tt('fr.fruits.apple', [], false); // NULL

As trans do, you can make replacements:

echo tt('messages.welcome'); //output: Hi,

:name.
echo tt('messages.welcome', ['name' =>
'John']); //output: Hi, John.

Pluralization. Translator::choice works like Laravel's trans_choice (see

Laravel Documentation), but with further arguments.

echo Translator::choice('en.fruits.apple', 5,
['color' => 'red'], false); // red apples.
echo tt('en.fruits.apple'); // :color apple|
apples.

Last, If you need to get all texts from a group.needle, use Transalor::texts

$texts = Transalor::texts('fruits.apple');
echo $texts->en; // apple
echo $texts->es; // manzana
echo $texts->fr; // NULL

3.2.Creating
You can create a text for an specific locale:

Translator::create('es.fruits.peach',
'durazno');

Or create multiple locales at the same time:

Translator::create('fruits.peach', [
'es' => 'durazno',
'en' => 'peach',
'fr' => 'pche'
]);

Also, you can add extra attributes. Of corse, extra columns attributes should
have been added to translations table and should have been included
in App\Translation::$fillable array property.

Translator::create('fruits.peach', [
'es' => 'durazno',
'en' => 'peach',
'fr' => 'pche'
], [
'type' => 'infotext',
'description' => 'Prunus persicas fruit'
]);
3.3.Updating

3.3.1.Updating a text

Update a text for a specific locale or a group of them, with or without extra
attributes:

Translator::update('es.fruits.peach',
'melocotn');
Translator::update('fruits.peach', [
'es' => 'melocotn',
'en' => 'peach'
],[
'type' => 'information'
]);

3.3.2.Updating a texts group name or needle

Groups and needle are sensitive attributes, this is, they cannot be updated
lightly without making a mess. In short, there cannot be duplicates for a
locale.group.needle. So, even if you try, Translator::update method will not
allow you to change this attributes. Instead, you must
use Translator::updateGroupNeedle.

// Change the whole group name:

Translator::updateGroupNeedle('fruits',
'juicy_fruits');

// Change the needle, but not the group:

Translator::updateGroupNeedle('fruits.peach',
'fruits.yellow_peach');

//Change a single group.needle:

Translator::updateGroupNeedle('fruits.peach',
'juicy_fruits.peach');
3.4.Deleting

Deleting is also easy with provided respository:

//Delete the whole group

Translator::delete('fruits');

//Delete the group.needle for all locales

Translator::delete('fruits.apple');

//Delete a group.needle for a specific locale

Translator::delete('es.fruits.apple');

4.Translatable Models
Laravel Translator includes, not only Translator repository, but also an
Eloquent extension to manage multiple languajes directly inside your Models.
Suppose you need an Article model. It would be truly helpful if you were able
to get properties like this:

$article = App\Article::find(1);
echo $article->title;
// output would be 'My title' if locale were
'en',
// but 'Mi ttulo' if locale were 'es';

4.1.Creating a table

Translatable columns have a clear syntaxis: column_name_locale. In order to

simplify creation, optionally you can use our Schema extension (rememeber
include facade. See #Installation). All you have to do is call $table-
>localize(['column_name']) to multiply column_name for each locale available in
application. Also, you can pass an array of locales as a second argument.

Schema::create('articles', function ($table) {

$table->increments('id');
$table->text('body');
 $table->string('title');
$table->timestamps();

$table->localize([ 'title', 'body' ]);

});

4.2.The Model

Two things must be done: to extend your model

to Translator\Eloquent\Model and to fill $translatable protected property.

class Article extends

Translator\Eloquent\Model
{
protected $translatable = ['title',
'body'];

protected $fillable = ['title', 'body'];

For the following examples, 'en' will be considered the current locale.
Remember current locale is a dynamic property.

Now, you can get a translatable property on any of the following ways.

$article = App\Article::find(1);
echo $article->title; // output 'My Title'
echo $article->title_en; // output 'My Title'
echo $article->title_es; // output 'Mi
ttulo'

$title = $article->trans('title');
echo $title->en; // output 'My Title'
echo $title->es; // output 'Mi ttulo'
To update, insert or fill a row for current locale, you are able to do it like you
usually do:

$article = App\Article::find(1);
$article->title = 'My Title in English';
$article->title_es = 'Mi ttulo en espaol';
$article->save();

But if you need to manage several locales at once, you can do it with an array,
just like this:

//Modify an article
$article = App\Article::find(1);
$article->title = [
'es' => 'Mi ttulo en espaol',
'en' => 'My title in English'
];
$article->save();

//Insert an article
$article = new App\Article;
$article->fill([
'title' => [
'es' => 'Mi ttulo en espaol',
'en' => 'My Title in English'
]
]);
$article->save();

CACHE
In order to reduce database queries, groups should be stored in cache. Just
look inside conf/translator.php and make sure that $cache is set TRUE. Laravel
Translation uses your application's cache settings.

If you are using (as you should) provided repository to create, update or delete
translations, then cache does not need to be flushed manually. Just be sure
that cache_auto_flush is set TRUE and cache will be automatically flushed only
for compromised groups each time
Translator's created, updated or deleted events are fired.

METHODS
1.TranslatorRespository (Facade: Translator)

Retur
Method
n
text($localeGroupNeedle, $replacements
string = [], $orDefault = true)
Get a text for a locale.group.needle.
texts($groupNeedle, $replacements = [])
object
Get all texts for a group.needle.
choice($localeGroupNeedle, $count = 1,
$replacements = [], $orDefault = true)
string
Choice between two or more string
options.
Collecti getGroup($name)
on Get a Collection from a group name.
getLocale($locale = NULL, $group =
Collecti NULL)
on Get a Collection from a locale and,
optionally, a group name.
cacheFlush($group = NULL)
void
Remove a group or all groups from cache.
Retur
Method
n
get($localeGroupNeedle = NULL)
Collecti Get a Collection from a locale (optionally),
on a group name and a needle. By default,
get current locale.
delete($localeGroupNeedle)
void Delete a whole group or a group.needle for
a specific locale or for all locales.
create($localeGroupNeedle, $texts, array
$extra = [])
void
Insert a text for an specific locale or for all
locales at once.
update($localeGroupNeedle, $texts, array
$extra = [])
void
Edit a text for an specific locale or for all
locales at once.
updateGroupNeedle($groupNeedle,
$newGroupNeedle)
void Edit the whole group name, edit the needle
but not the group or edit a single
group.needle row:
created(Closure $callback)
void Register a listener for created event.
Callback's params: array $locales, $group, $needle.
void updated(Closure $callback)
Register a listener for updated event.
 Retur
Method
n
Callback's params: array $locales, $group, $needle.
deleted(Closure $callback)
void Register a listener for deleted event.
Callback's params: array $locales, $group, $needle.

2.TranslatorURL (Facade: URL)

TranslatorURL extends URLGenerator.

Retu
Method
rn
route($name, $parameters = [], $absolute
= true, $default = NULL)
string Get the URL to a named route and locale
(current locale, by default). Use dot
notation.
routes($name, $parameters = [],
$absolute = true)
object
Get an object with all URLs for all locales to
a named route.
current($locale = NULL, $absolute = true)
string Get the current URL for current locale or for
another supported locale.
currentAll($absolute = true)
array
Get all current URLs for all locales available.
bool hasRouteLocale($route, $locale)
 Retu
Method
rn
Verify if route has a locale.
hasLocale($routename, $locale)
bool
Verify if a route' name has a locale.
localize($uri, $locale, $absolute = true,
$uriHasPrefix = true)
string
Generate an absolute or relative URL for a
given URI and a locale.

LICENSE
Laravel Translator is licensed under the MIT License.

Copyright 2016 ngel Espro