Skip to content
Laravel translation made __('simple').
Branch: master
Clone or download
Latest commit e0a793d Sep 9, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
config change package name to tio/laravel, rename config to translation.php,… Mar 23, 2018
src bump to version 1.6 Jan 31, 2019
tests bump to version 1.6 Jan 31, 2019
.gitattributes init Oct 3, 2017
.gitignore Gettext methods are working, Gettext tests with VCR and evaluation of… Feb 22, 2018
.travis.yml Add php 7.2 Sep 9, 2019 bump to version 1.6 Jan 31, 2019 repear links Mar 7, 2018
LICENSE init Oct 3, 2017 Remove extra-space on README Apr 15, 2019
composer.json wording composer Aug 8, 2018
routes.php init Oct 3, 2017 client for Laravel 5

Software License Build Status Test Coverage Maintainability

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 interface

Technical Demo (2.5min)

Need help?

Table of contents

Translation syntaxes

Laravel Localization (PHP key/values)

The default Laravel method to localize.

// Regular

// Regular with sublevel key

// Pluralization
trans_choice('inbox.message', $number);

// Interpolation
__('inbox.hello', ['name' => $user->name]);

With the PHP file resources/lang/en/inbox.php:

return [
    'title' => 'Title to be translated',
    'hello' => 'Hello :name',
    'messages' => 'One message|Many messages',
    'menu' => [
        'title' => 'Title of menu'

Note that trans can also be used instead of __.

Laravel Localization (JSON source text)

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 resources/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 resources/lang/en.json:

    "Text to be translated": "",
    "One message|Many messages": "",
    "Hello :name": ""

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.


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.

Also, 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' ]);


  1. Add the package via Composer:
$ composer require tio/laravel

If you are on a Laravel version lower than 5.5 (or choose not to use package auto discovery) add this to service providers (config/app.php):

  1. Create a new translation project from the UI.
  2. Copy the initializer into your Laravel app (config/translation.php) or execute php artisan vendor:publish.

The initializer looks like this:

return [
    'key' => env('TRANSLATIONIO_KEY'),
    'source_locale' => 'en',
    'target_locales' => ['fr', 'nl', 'de', 'es'],
    'gettext_parse_paths' => ['app', 'resources'],     // Where the GetText strings will be scanned
    'gettext_locales_path' => 'resources/lang/gettext' // Where the GetText translations will be stored
  1. Add the API key (TRANSLATIONIO_KEY) in your .env file.
  2. Initialize your project and push existing translations to with:
$ php artisan translation:init

If you later need to add/remove target languages, please read our this section about that.



To send new translatable keys/strings and get new translations from, simply run:

$ php artisan translation:sync

Sync and Show Purgeable

If you need to find out what are the unused keys/strings from, 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.

Sync and Purge

If you need to remove unused keys/strings from, 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 branch will be permanently deleted from

Manage Languages

Add or Remove Language

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 folder), you will need to create a new project on and run php artisan translation:init for them to appear.

Edit Language

To edit existing languages while keeping their translations (e.g. changing from en to en-US).

  1. Create a new project on with the correct languages.
  2. Adapt config/translation.php (new API key and languages)
  3. Adapt directory language names in resources/lang (optional: adapt GetText .po headers)
  4. Execute php artisan translation:init and check that everything went fine.
  5. Invite your collaborators in the new project.
  6. Remove the old project.

Since you created a new project, the translation history and tags will unfortunately be lost.

Custom Languages

You may want to add a custom language that is derived from an existing language. It's useful if you want to change some translations for another instance of the application or for a specific customer.

The structure of a custom language is : existing language code + "-" + custom text.

Examples: en-microsoft or fr-BE-custom.

Custom languages can be added and used like any other language.

Change the current locale


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
Route::get('/', function () {
    return view('welcome');

// Solution 2: Apply the locale selection to many routes
Route::middleware('set.locale')->group(function () {
    Route::get('/', function () {
        return view('welcome');

// Solution 3: prefix your routes with the locale and apply it
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.

Update the user locale by redirecting to or (Solution 3)

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;



To run the specs:

$ phpunit


Please read the CONTRIBUTING file.

List of clients for

These implementations were usually started by contributors for their own projects. Some of them are officially supported by and some are not yet supported. However, they are quite well documented.

Thanks a lot to these contributors for their hard work!

Ruby on Rails (Ruby)

Officially Supported on

Credits: @aurels, @michaelhoste

Laravel (PHP)

Officially Supported on

Credits: @armandsar, @michaelhoste

React and React-Intl (JavaScript)

Credits: @deecewan


If you want to create a new client for your favorite language or framework, feel free to reach us on and we'll assist you with the workflow logic and send you API docs.


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

You can’t perform that action at this time.