Keeping a project's translations properly updated is cumbersome. Usually translators do not have access to the codebase, and even when they do it's hard to keep track of which translations are missing for each language or when updates to the original text require that translations be revised.
This package allows developers to leverage their database and cache to manage multilanguage sites, while still working on language files during development and benefiting from all the features Laravel's Translation bundle has, like pluralization or replacement.
WAAVI is a web development studio based in Madrid, Spain. You can learn more about us at waavi.com
- Laravel compatibility
- Features overview
- Installation
- Set source for translations
- Cache translations
- Managing languages and translations in the Database
- Model attributes translation
- Uri localization
| Laravel | translation |
|---|---|
| 4.x | 1.0.x |
| 5.0.x | 2.0.x |
| 5.1.x|5.3.x | 2.1.x |
| 5.4.x | 2.2.x |
| 5.5.x | 2.3.x and higher |
| 5.6.x | 2.3.x and higher |
| 6.x|7.x | 2.4.x and higher |
| 8.x.x | 2.5.x and higher |
- Allow dynamic changes to the site's text and translations.
- Cache your localization entries.
- Load your translation files into the database.
- Force your urls to be localized (ex: /home -> /es/home) and set the locale automatically through the browser's config.
- Localize your model attributes.
Require through composer
composer require waavi/translation 2.5.x
Or manually edit your composer.json file:
"require": {
"waavi/translation": "2.5.x"
}
Once installed, in your project's config/app.php file replace the following entry from the providers array:
Illuminate\Translation\TranslationServiceProvider::class
with:
Waavi\Translation\TranslationServiceProvider::class
Remove your config cache:
php artisan config:clear
Publish both the configuration file and the migrations:
php artisan vendor:publish --provider="Waavi\Translation\TranslationServiceProvider"
Execute the database migrations:
php artisan migrate
You may check the package's configuration file at:
config/translator.php
This package allows you to load translation from the regular Laravel localization files (in /lang), from the database, from cache or in a mix of the previous for development. You may configure the desired mode of operation through the translator.php config file and/or the TRANSLATION_SOURCE environment variable. Accepted values are:
- 'files' To load translations from Laravel's language files (default)
- 'database' To load translations from the database
- 'mixed' To load translations both from the filesystem and the database, with the filesystem having priority.
- 'mixed_db' To load translations both from the filesystem and the database, with the database having priority. [v2.1.5.3]
NOTE: When adding the package to an existing Laravel project, 'files' must be used until migrations have been executed.
For cache configuration, please go to cache configuration
If you do not wish to leverage your database for translations, you may choose to load language lines exclusively through language files. This mode differs from Laravel in that, in case a line is not found in the specified locale, instead of returning the key right away, we first check the default language for an entry. In case you wish to use this mode exclusively, you will need to set the 'available_locales' config file:
config/translator.php
'available_locales' => ['en', 'es', 'fr'],
Example:
The content in en/validations.php, where 'en' is the default locale, is:
[
'missing_name' => 'Name is missing',
'missing_surname' => 'Surname is missing',
];The content in es/validations.php is:
[
'missing_name' => 'Falta el nombre',
];Output for different keys with 'es' locale:
trans('validations.missing_name'); // 'Falta el nombre'
trans('validations.missing_surname'); // 'Surname is missing'
trans('validations.missing_email'); // 'validations.missing_email'You may choose to load translations exclusively from the database. This is very useful if you intend to allow users or administrators to live edit the site's text and translations. In a live production environment, you will usually want this source mode to be activated with the translation's cache. Please see Loading your files into the database for details on the steps required to use this source mode.
Example:
The content in the languages table is:
| id | locale | name |
-------------------------
| 1 | en | english |
| 2 | es | spanish |
The relevant content in the language_entries table is:
| id | locale | namespace | group | item | text |
-------------------------------------------------------------------------------------
| 1 | en | * | validations | missing.name | Name is missing |
| 2 | en | * | validations | missing.surname | Surname is missing |
| 3 | en | * | validations | min_number | Number is too small |
| 4 | es | * | validations | missing.name | Falta nombre |
| 5 | es | * | validations | missing.surname | Falta apellido |
Output for different keys with es locale:
trans('validations.missing.name'); // 'Falta nombre'
trans('validations.min_number'); // 'Number is too small'
trans('validations.missing.email'); // 'missing_email'In mixed mode, both the language files and the database are queried when looking for a group of language lines. Entries found in the filesystem take precedence over the database. This source mode is useful when in development, so that both the filesystem and the user entries are taken into consideration.
Example:
When files and database are set like in the previous examples:
trans('validations.missing_name'); // 'Falta el nombre'
trans('validations.missing_surname'); // 'Falta apellido'
trans('validations.min_number'); // 'Number is too small'
trans('validations.missing_email'); // 'missing_email'When using either the database or mixed translation sources, you will need to first load your translations into the database. To do so, follow these steps:
-
Run the migrations detailed in the installation instructions.
-
Add your languages of choice to the database (see Managing Database Languages)
-
Load your language files into the database using the provided Artisan command:
php artisan translator:load
When executing the artisan command, the following will happen:
- Non existing entries will be created.
- Existing entries will be updated except if they're locked. When allowing users to live edit the translations, it is recommended you do it throught the updateAndLock method provided in the Translations repository. This prevents entries being overwritten when reloading translations from files.
- When an entry in the default locale is edited, all of its translations will be flagged as pending review. This gives translators the oportunity to review translations that might not be correct, but doesn't delete them so as to avoid minor errata changes in the so 8000 urce text from erasing all translations. See Managing translations for details on how to work with unstable translations.
Both vendor files and subdirectories are supported. Please keep in mind that when loading an entry inside a subdirectory, Laravel 5 has changed the syntax to:
trans('subdir/file.entry')
trans('package::subdir/file.entry')Since querying the database everytime a language group must be loaded is grossly inefficient, you may choose to leverage Laravel's cache system. This module will use the same cache configuration as defined by you in app/config/cache.php.
You may enable or disable the cache through the translator.php config file or the 'TRANSLATION_CACHE_ENABLED' environment variable. Config options are:
| Env key | type | description |
|---|---|---|
| TRANSLATION_CACHE_ENABLED | boolean | Enable / disable the translations cache |
| TRANSLATION_CACHE_TIMEOUT | integer | Minutes translation items should be kept in the cache. |
| TRANSLATION_CACHE_SUFFIX | string | Default is 'translation'. This will be the cache suffix applied to all translation cache entries. |
Available since version 2.1.3.8, if the cache store in use allows for tags, the TRANSLATION_CACHE_SUFFIX will be used as the common tag to all cache entries. This is recommended to be able to invalidate only the translation cache, or even just a given locale, namespace and group configuration.
Available since version 2.1.3.8, you may clear the translation cache through both an Artisan Command and a Facade. If cache tags are in use, only the translation cache will be cleared. All of your application cache will however be cleared if you cache tags are not available.
Cache flush command:
php artisan translator:flush
In order to access the translation cache, add to your config/app.php files, the following alias:
'aliases' => [
/* ... */
'TranslationCache' => \Waavi\Translation\Facades\TranslationCache::class,
]Once done, you may clear the whole translation cache by calling:
\TranslationCache::flushAll();You may also choose to invalidate only a given locale, namespace and group combination.
\TranslationCache::flush($locale, $group, $namespace);- The locale is the language locale you wish to clear.
- The namespace is either '*' for your application translation files, or 'package' for vendor translation files.
- The group variable is the path to the translation file you wish to clear.
For example, say we have the following file in our lang directory: en/auth.php, en/auth/login.php and en/vendor/waavi/login.php. To clear the cache entries for each of them you would call:
\TranslationCache::flush('en', 'auth', '*');
\TranslationCache::flush('en', 'auth/login', '*');
\TranslationCache::flush('en', 'login', 'waavi');The recommended way of managing both languages and translations is through the provided repositories. You may circumvent this by saving changes directly through the Language and Translation models, however validation is no longer executed automatically on model save and could lead to instability and errors.
Both the Language and the Translation repositories provide the following methods:
| Method | Description |
|---|---|
| hasTable(); | Returns true if the corresponding table exists in the database, false otherwise |
| all($related = [], $perPage = 0); | Retrieve all records from the DB. A paginated record will be return if the second argument is > 0, with $perPage items returned per page |
| find($id); | Find a record by id |
| create($attributes); | Validates the given attributes and inserts a new record. Returns false if validation errors occured |
| delete($id); | Delete a record by id |
| restore($id); | Restore a record by id |
| count(); | Return the total number of entries |
| validate(array $attributes); | Checks if the given attributes are valid |
| validationErrors(); | Get validation errors for create and update methods |
Language management should be done through the \Waavi\Translation\Repositories\LanguageRepository to ensure proper data validation before inserts and updates. It is recommended that you instantiate this class through Dependency Injection.
A valid Language record requires both its name and locale to be unique. It is recommended you use the native name for each language (Ex: English, Español, Français)
The provided methods are:
| Method | Description |
|---|---|
| update(array $attributes); | Updates a Language entry [id, name, locale] |
| trashed($related = [], $perPage = 0); | Retrieve all trashed records from the DB. |
| findTrashed($id, $related = []); | Find a trashed record by id |
| findByLocale($locale); | Find a record by locale |
| findTrashedByLocale($locale); | Finds a trashed record by locale |
| allExcept($locale); | Returns a list of all languages excluding the given locale |
| availableLocales(); | Returns a list of all available locales |
| isValidLocale($locale); | Checks if a language exists with the given locale |
| percentTranslated($locale); | Returns the percent translated for the given locale |
Translation management should be done through the \Waavi\Translation\Repositories\TranslationRepository to ensure proper data validation before inserts and updates. It is recommended that you instantiate this class through Dependency Injection.
A valid translation entry cannot have the same locale and language code than another.
The provided methods are:
| Method | Description |
|---|---|
| update($id, $text); | Update an unlocked entry |
| updateAndLock($id, $text); | Update and lock an entry (locked or not) |
| allByLocale($locale, $perPage = 0); | Get all by locale |
| untranslated($locale, $perPage = 0, $text = null); | Get all untranslated entries. If $text is set, entries will be filtered by partial matches to translation value. |
| pendingReview($locale, $perPage = 0); | List all entries pending review |
| search($locale, $term, $perPage = 0); | Search by all entries by locale and a partial match to both the text value and the translation code. |
| randomUntranslated($locale); | Get a random untranslated entry |
| translateText($text, $textLocale, $targetLocale); | Translate text to another locale |
| flagAsReviewed($id); | Flag entry as reviewed |
Things to consider:
- You may lock translations so that they can only be updated through updateAndLock. The language file loader uses the update method and will not be able to override locked translations.
- When a text entry belonging to the default locale is updated, all of its siblings are marked as pending review.
- When deleting an entry, if it belongs to the default locale its translations will also be deleted.
You can also use the translation management system to manage your model attributes translations. To do this, you only need to:
- Make sure either the database or mixed source are set.
- Make sure your models use the Waavi\Translation\Translatable\Trait
- In your model, add a translatableAttributes array with the names of the attributes you wish to be available for translation.
- For every field you wish to translate, make sure there is a corresponding attributeName_translation field in your database.
Example:
\Schema::create('examples', function ($table) {
$table->increments('id');
$table->string('slug')->nullable();
$table->string('title')->nullable();
$table->string('title_translation')->nullable();
$table->string('text')->nullable();
$table->string('text_translation')->nullable();
$table->timestamps();
});
class Example extends Model
{
use \Waavi\Translation\Traits\Translatable;
protected $translatableAttributes = ['title', 'text'];
}You may use Waavi\Translation\Middleware\TranslationMiddleware to make sure all of your urls are properly localized. The TranslationMiddleware will only redirect GET requests that do not have a locale in them.
For example, if a user visits the url /home, the following would happen:
- The middleware will check if a locale is present.
- If a valid locale is present:
- it will globally set the language for that locale
- the following data will be available in your views:
- currentLanguage: current selected Language instance.
- selectableLanguages: list of all languages the visitor can switch to (except the current one)
- altLocalizedUrls: a list of all localized urls for the current resource except this one, formatted as ['locale' => 'en', 'name' => 'English', 'url' => '/en/home']
- If no locale is present:
- Check the first two letters of the brower's accepted locale HTTP_ACCEPT_LANGUAGE (for example 'en-us' => 'en')
- If this is a valid locale, redirect the visitor to that locale => /es/home
- If not, redirect to default locale => /en/home
- Redirects will keep input data in the url, if any
You may choose to activate this Middleware globally by adding the middleware to your App\Http\Kernel file:
protected $middleware = [
/* ... */
\Waavi\Translation\Middleware\TranslationMiddleware::class,
]Or to apply it selectively through the 'localize' route middleware, which is already registered when installing the package through the ServiceProvider.
It is recommended you add the following alias to your config/app.php aliases:
'aliases' => [
/* ... */
'UriLocalizer' => Waavi\Translation\Facades\UriLocalizer::class,
];Every localized route must be prefixed with the current locale:
// If the middleware is globally applied:
Route::group(['prefix' => \UriLocalizer::localeFromRequest()], function(){
/* Your routes here */
});
// For selectively chosen routes:
Route::group(['prefix' => \UriLocalizer::localeFromRequest(), 'middleware' => 'localize')], function () {
/* Your routes here */
});Starting on v2.1.6, you may also specify a custom position for the locale segment in your url. For example, if the locale info is the third segment in a URL (/api/v1/es/my_resource), you may use:
// For selectively chosen routes:
Route::group(['prefix' => 'api/v1'], function() {
/** ... Non localized urls here **/
Route::group(['prefix' => \UriLocalizer::localeFromRequest(2), 'middleware' => 'localize:2')], function () {
/* Your localized routes here */
});
});In your views, for routes where the Middleware is active, you may present the user with a menu to switch from the current language to another by using the shared variables. For example:
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">{{ $currentLanguage->name }} <b class="caret"></b></a>
<ul class="dropdown-menu">
@foreach ($altLocalizedUrls as $alt)
<li><a href="{{ $alt['url'] }}" hreflang="{{ $alt['locale'] }}">{{ $alt['name'] }}</a></li>
@endforeach
</ul>
</li>