Translation.io client for Laravel 5.5+ to 11.x
Add this package to localize your Laravel application.
Use the official Laravel syntax (with PHP or JSON files), or use the GetText syntax.
Write only the source text, and keep it synchronized with your translators on Translation.io.
Technical Demo (2.5min)
Need help? [email protected]
- Localization syntaxes
- Installation
- Usage
- Manage Languages
- Change the current locale
- Frontend Localization
- Advanced Configuration Options
- Testing
- Contributing
- List of clients for Translation.io
- License
The default Laravel method to localize.
// Regular
__('inbox.title');
// Regular with sublevel key
__('inbox.menu.title');
// Pluralization
trans_choice('inbox.messages', $number);
// Interpolation
__('inbox.hello', ['name' => $user->name]);
With the PHP file lang/en/inbox.php
:
<?php
return [
'title' => 'Title to be translated',
'hello' => 'Hello :name',
'messages' => 'One message|Many messages',
'menu' => [
'title' => 'Title of menu'
]
];
Notes:
trans
can also be used instead of__
.- You can organize your PHP files with subfolders like
en/subfolder/inbox.php
using keys likesubfolder/inbox.title
.
A new feature of Laravel 5.4
is the possibility to use __
with the source text (and not only with keys like in the previous section).
These translations are stored into JSON files located in the lang
directory.
// Regular
__("Text to be translated");
// Pluralization
trans_choice(__('One message|Many messages'), $number);
// Interpolation
__('Hello :name', ['name' => $user->name]);
With the JSON file lang/en.json
:
{
"Text to be translated": "",
"One message|Many messages": "",
"Hello :name": ""
}
Notes:
-
To spend less time dealing with multiple JSON files, we advise to only edit the original language (usually
en.json
) to add new strings, and leave the translations empty. During a sync, This package will automatically create and fill the JSON files of the target languages. -
If you want to organize your JSON files by feature, you can register new paths in
AppServiceProvider
like this:
public function boot()
{
$loader = $this->app['translation.loader'];
// or 'resources/lang/my_feature' in Laravel < 9
$loader->addJsonPath(base_path('lang/my_feature'));
}
This package adds the GetText support to Laravel. We strongly suggest that you use GetText to localize your application since it allows an easier and more complete syntax.
Moreover, you won't need to create and manage any PHP or JSON file since your code will be automatically scanned for any string to translate.
// Regular
t("Text to be translated");
// Pluralization
n("Singular text", "Plural text", $number);
// Regular with context
p("context", "Text to be translated");
// Pluralization with context
np("context", "Singular text", "Plural text", $number);
// Simple Interpolations (works with n, p and np too)
t('Hello %s', $user->name);
// Complex Interpolations (works with n, p and np too)
t(':city1 is bigger than :city2', [ ':city1' => 'NYC', ':city2' => 'BXL' ]);
- Add the package via Composer:
composer require tio/laravel
- Create a new translation project from the UI.
- Copy the initializer into your Laravel app (
config/translation.php
) or executephp artisan vendor:publish
.
The initializer looks like this:
<?php
return [
'key' => env('TRANSLATIONIO_KEY'),
'source_locale' => 'en',
'target_locales' => ['fr', 'nl', 'de', 'es']
];
- Add the API key (
TRANSLATIONIO_KEY
) in your.env
file. - Initialize your project and push existing translations to Translation.io with:
php artisan translation:init
Note: since Laravel 9, the lang
directory and the default set of language files
used by Laravel are not included by default in new projects
(see official documentation),
so you may need to run the lang:publish
command to generate them:
php artisan lang:publish
If you need to add or remove languages in the future, please read this section about that.
To send new translatable keys/strings and get new translations from Translation.io, simply run:
php artisan translation:sync
If you need to find out what are the unused keys/strings from Translation.io, using the current branch as reference:
php artisan translation:sync_and_show_purgeable
As the name says, this operation will also perform a sync at the same time.
If you need to remove unused keys/strings from Translation.io, using the current branch as reference:
php artisan translation:sync_and_purge
As the name says, this operation will also perform a sync at the same time.
Warning: all keys that are not present in the current local branch will be permanently deleted from Translation.io.
You can add or remove a language by updating 'target_locales' => []
in your
config/translation.php
file, and executing php artisan translation:sync
.
If you want to add a new language with existing translations (ex. if you already have
a translated PHP file in your lang
directory), you will need to create a new project on
Translation.io and run php artisan translation:init
for them to appear.
To edit existing languages while keeping their translations (e.g. changing from en
to en-US
).
- Create a new project on Translation.io with the correct languages.
- Adapt
config/translation.php
(new API key and languages) - Adapt directory language names in
lang
orresources/lang
(optional: adapt GetText.po
headers) - Execute
php artisan translation:init
and check that everything went fine. - Invite your collaborators in the new project.
- Remove the old project.
Since you created a new project, the translation history and tags will unfortunately be lost.
A custom language is always derived from an existing language. It's useful if you want to adapt some translations to another instance of your application, or to a specific customer.
The structure of a custom language is: existing language code
+ -
+ custom text
, where
custom text
can only contain alphanumeric characters and -
.
Examples: en-microsoft
or fr-BE-custom
.
Custom languages can be added and used like any other language.
The easiest way to change the current locale is with the set.locale
Middleware.
// in routes/web.php
// Solution 1: Apply the locale selection to root.
// => https://yourdomain.com?locale=fr
Route::get('/', function () {
return view('welcome');
})->middleware('set.locale');
// Solution 2: Apply the locale selection to many routes.
// => https://yourdomain.com/...?locale=fr
Route::middleware('set.locale')->group(function () {
Route::get('/', function () {
return view('welcome');
});
});
// Solution 3: prefix your routes with the locale and apply it.
// => https://yourdomain.com/fr
// => https://yourdomain.com/fr/...
Route::prefix('{locale?}')->middleware('set.locale')->group(function() {
Route::get('/', function () {
return view('welcome');
});
});
First time the user will connect, it will automatically set the locale extracted
from the browser HTTP_ACCEPT_LANGUAGE
value, and keep it in the session between
requests.
The set.locale
Middleware code is here,
feel free to adapt it with your own locale management.
Change the current locale with:
use Tio\Laravel\Facade as Translation;
Translation::setLocale('fr');
This package is also able to cover frontend localization (React, Vue, ...).
There are several ways to pass the translation strings from the backend
to the frontend: JavaScript serialization, data-
HTML attributes, JSON files etc.
The easiest strategy when dealing with React/Vue would be to pass the corresponding translations as props when mounting the components.
Notes:
- You can structure the i18n props with multiple levels of depth and pass the subtree as props to each of your sub-components.
- It also works great with server-side rendering of your components.
As Translation.io is directly integrated in the great Lingui internationalization framework, you can also consider frontend localization as a completely different localization project.
Please read more about this on:
- Website: https://translation.io/lingui
- GitHub page: https://github.com/translation/lingui
The config/translation.php
file can take several optional configuration options.
Some options are described below but for an exhaustive list, please refer to translation.php.
If you would like to ignore specific PHP keys, or even entire PHP files or
subdirectories from the source language, you can use the ignored_key_prefixes
option.
For example:
<?php
return [
...
'ignored_key_prefixes' => [
'validation', // ignore the whole validation.php file.
'validation.custom', // ignore the "custom" subtree in validation.php file.
'subfolder/more', // ignore the whole subfolder/more.php file.
],
...
];
To run the specs with oldest dependencies:
composer update --no-interaction --prefer-stable --prefer-lowest
./vendor/bin/phpunit
To run the specs with latest dependencies:
composer update --no-interaction --prefer-stable
./vendor/bin/phpunit
Please read the CONTRIBUTING file.
The following clients are officially supported by Translation.io and are well documented.
Some of these implementations (and other non-officially supported ones) were started by contributors for their own translation projects. We are thankful to all contributors for their hard work!
Officially supported on https://translation.io/rails
- GitHub: https://github.com/translation/rails
- RubyGems: https://rubygems.org/gems/translation/
Credits: @aurels, @michaelhoste
Officially supported on https://translation.io/laravel
- GitHub: https://github.com/translation/laravel
- Packagist: https://packagist.org/packages/tio/laravel
Credits: @armandsar, @michaelhoste
Officially supported on https://translation.io/lingui
Translation.io is directly integrated in the great Lingui internationalization project.
- GitHub: https://github.com/translation/lingui
- NPM: https://www.npmjs.com/package/@translation/lingui
Officially supported on https://translation.io/angular
- GitHub: https://github.com/translation/angular
- NPM: https://www.npmjs.com/package/@translation/angular
Credits: @SimonCorellia, @didier-84, @michaelhoste
If you want to create a new client for your favorite language or framework, please read our Create a Translation.io Library guide and use the special init and sync endpoints.
You can also use the more traditional API.
Feel free to contact us on [email protected] if you need some help or if you want to share your library.
The MIT License (MIT). Please see License File for more information.