Skip to content

Latest commit

 

History

History
263 lines (172 loc) · 13 KB

localization.md

File metadata and controls

263 lines (172 loc) · 13 KB
Raw

Localization

Introduction

Note By default, the Laravel application skeleton does not include the lang directory. If you would like to customize Laravel's language files, you may publish them via the lang:publish Artisan command.

Laravel's localization features provide a convenient way to retrieve strings in various languages, allowing you to easily support multiple languages within your application.

Laravel provides two ways to manage translation strings. First, language strings may be stored in files within the application's lang directory. Within this directory, there may be subdirectories for each language supported by the application. This is the approach Laravel uses to manage translation strings for built-in Laravel features such as validation error messages:

/lang
    /en
        messages.php
    /es
        messages.php

Or, translation strings may be defined within JSON files that are placed within the lang directory. When taking this approach, each language supported by your application would have a corresponding JSON file within this directory. This approach is recommended for applications that have a large number of translatable strings:

/lang
    en.json
    es.json

We'll discuss each approach to managing translation strings within this documentation.

Publishing The Language Files

By default, the Laravel application skeleton does not include the lang directory. If you would like to customize Laravel's language files or create your own, you should scaffold the lang directory via the lang:publish Artisan command. The lang:publish command will create the lang directory in your application and publish the default set of language files used by Laravel:

php artisan lang:publish

Configuring The Locale

The default language for your application is stored in the config/app.php configuration file's locale configuration option. You are free to modify this value to suit the needs of your application.

You may modify the default language for a single HTTP request at runtime using the setLocale method provided by the App facade:

use Illuminate\Support\Facades\App;

Route::get('/greeting/{locale}', function (string $locale) {
    if (! in_array($locale, ['en', 'es', 'fr'])) {
        abort(400);
    }

    App::setLocale($locale);

    // ...
});

You may configure a "fallback language", which will be used when the active language does not contain a given translation string. Like the default language, the fallback language is also configured in the config/app.php configuration file:

'fallback_locale' => 'en',

Determining The Current Locale

You may use the currentLocale and isLocale methods on the App facade to determine the current locale or check if the locale is a given value:

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

if (App::isLocale('en')) {
    // ...
}

Pluralization Language

You may instruct Laravel's "pluralizer", which is used by Eloquent and other portions of the framework to convert singular strings to plural strings, to use a language other than English. This may be accomplished by invoking the useLanguage method within the boot method of one of your application's service providers. The pluralizer's currently supported languages are: french, norwegian-bokmal, portuguese, spanish, and turkish:

use Illuminate\Support\Pluralizer;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Pluralizer::useLanguage('spanish');     

    // ...     
}

Warning
If you customize the pluralizer's language, you should explicitly define your Eloquent model's table names.

Defining Translation Strings

Using Short Keys

Typically, translation strings are stored in files within the lang directory. Within this directory, there should be a subdirectory for each language supported by your application. This is the approach Laravel uses to manage translation strings for built-in Laravel features such as validation error messages:

/lang
    /en
        messages.php
    /es
        messages.php

All language files return an array of keyed strings. For example:

<?php

// lang/en/messages.php

return [
    'welcome' => 'Welcome to our application!',
];

Warning
For languages that differ by territory, you should name the language directories according to the ISO 15897. For example, "en_GB" should be used for British English rather than "en-gb".

Using Translation Strings As Keys

For applications with a large number of translatable strings, defining every string with a "short key" can become confusing when referencing the keys in your views and it is cumbersome to continually invent keys for every translation string supported by your application.

For this reason, Laravel also provides support for defining translation strings using the "default" translation of the string as the key. Language files that use translation strings as keys are stored as JSON files in the lang directory. For example, if your application has a Spanish translation, you should create a lang/es.json file:

{
    "I love programming.": "Me encanta programar."
}

Key / File Conflicts

You should not define translation string keys that conflict with other translation filenames. For example, translating __('Action') for the "NL" locale while a nl/action.php file exists but a nl.json file does not exist will result in the translator returning the entire contents of nl/action.php.

Retrieving Translation Strings

You may retrieve translation strings from your language files using the __ helper function. If you are using "short keys" to define your translation strings, you should pass the file that contains the key and the key itself to the __ function using "dot" syntax. For example, let's retrieve the welcome translation string from the lang/en/messages.php language file:

echo __('messages.welcome');

If the specified translation string does not exist, the __ function will return the translation string key. So, using the example above, the __ function would return messages.welcome if the translation string does not exist.

If you are using your default translation strings as your translation keys, you should pass the default translation of your string to the __ function;

echo __('I love programming.');

Again, if the translation string does not exist, the __ function will return the translation string key that it was given.

If you are using the Blade templating engine, you may use the {{ }} echo syntax to display the translation string:

{{ __('messages.welcome') }}

Replacing Parameters In Translation Strings

If you wish, you may define placeholders in your translation strings. All placeholders are prefixed with a :. For example, you may define a welcome message with a placeholder name:

'welcome' => 'Welcome, :name',

To replace the placeholders when retrieving a translation string, you may pass an array of replacements as the second argument to the __ function:

echo __('messages.welcome', ['name' => 'dayle']);

If your placeholder contains all capital letters, or only has its first letter capitalized, the translated value will be capitalized accordingly:

'welcome' => 'Welcome, :NAME', // Welcome, DAYLE
'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle

Object Replacement Formatting

If you attempt to provide an object as a translation placeholder, the object's __toString method will be invoked. The __toString method is one of PHP's built-in "magic methods". However, sometimes you may not have control over the __toString method of a given class, such as when the class that you are interacting with belongs to a third-party library.

In these cases, Laravel allows you to register a custom formatting handler for that particular type of object. To accomplish this, you should invoke the translator's stringable method. The stringable method accepts a closure, which should type-hint the type of object that it is responsible for formatting. Typically, the stringable method should be invoked within the boot method of your application's AppServiceProvider class:

use Illuminate\Support\Facades\Lang;
use Money\Money;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Lang::stringable(function (Money $money) {
        return $money->formatTo('en_GB');
    });
}

Pluralization

Pluralization is a complex problem, as different languages have a variety of complex rules for pluralization; however, Laravel can help you translate strings differently based on pluralization rules that you define. Using a | character, you may distinguish singular and plural forms of a string:

'apples' => 'There is one apple|There are many apples',

Of course, pluralization is also supported when using translation strings as keys:

{
    "There is one apple|There are many apples": "Hay una manzana|Hay muchas manzanas"
}

You may even create more complex pluralization rules which specify translation strings for multiple ranges of values:

'apples' => '{0} There are none|[1,19] There are some|[20,*] There are many',

After defining a translation string that has pluralization options, you may use the trans_choice function to retrieve the line for a given "count". In this example, since the count is greater than one, the plural form of the translation string is returned:

echo trans_choice('messages.apples', 10);

You may also define placeholder attributes in pluralization strings. These placeholders may be replaced by passing an array as the third argument to the trans_choice function:

'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago',

echo trans_choice('time.minutes_ago', 5, ['value' => 5]);

If you would like to display the integer value that was passed to the trans_choice function, you may use the built-in :count placeholder:

'apples' => '{0} There are none|{1} There is one|[2,*] There are :count',

Handling Missing Translation Strings

Typically, when attempting to translate a string that does not have a corresponding key in your language files, Laravel will return the translation string key.

You may customize or intercept this behavior using the handleMissingKeysUsing method. Typically, you should invoke this method in the boot method of your application's AppServiceProvider:

use Illuminate\Support\Facades\Lang;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Lang::handleMissingKeysUsing(function (string $key, array $replacements, string $locale) {
        info("Missing translation key [$key] detected.");

        return $key;
    });
}

Overriding Package Language Files

Some packages may ship with their own language files. Instead of changing the package's core files to tweak these lines, you may override them by placing files in the lang/vendor/{package}/{locale} directory.

So, for example, if you need to override the English translation strings in messages.php for a package named skyrim/hearthfire, you should place a language file at: lang/vendor/hearthfire/en/messages.php. Within this file, you should only define the translation strings you wish to override. Any translation strings you don't override will still be loaded from the package's original language files.