Laravel Localization: The File Loader

The FileLoader is the class that is responsible for loading the translation files from the file system. The language files are loaded from the /resources/lang/ directory by default. The lang/ directory contains the en (English from the ISO 639-1 standard) sub-directory by default. Each sub-directory within the lang/ directory corresponds to a particular locale.

Each locale directory may contain various PHP files returning arrays. These arrays contain a key/value pair, indicating the key of the translation and the value of the language translation. For example, the following is the contents of the /resources/lang/en/passwords.php file:

 1<?php
 2
 3return [
 4
 5    /*
 6    |-------------------------------------------------------------------------
 7    | Password Reminder Language Lines
 8    |-------------------------------------------------------------------------
 9    |
10    | The following language lines are the default lines which match reasons
11    | that are given by the password broker for a password update attempt
12    | has failed, such as for an invalid token or invalid new password.
13    |
14    */
15
16    'password' => 'Passwords must be at least six characters and match the
17                   confirmation.',
18    'user' => "We can't find a user with that e-mail address.",
19    'token' => 'This password reset token is invalid.',
20    'sent' => 'We have e-mailed your password reset link!',
21    'reset' => 'Your password has been reset!',
22
23];

The individual PHP files containing the translation lines are referred to as "groups". So for a fresh Laravel installation, the following groups exist:

#FileLoader Public API

The FileLoader implements the Illuminate\Translation\LoaderInterface contract. The LoaderInterface requires two public methods load and addNamespace. FileLoader does not add any extra public methods to its implementation.

#load($locale, $group, $namespace = null)

The load method is used to load the messages for the provided $locale. The load method also requires a $group to be specified. The $group corresponds to the actual file of key/value pairs that should be loaded (such as pagination.php or passwords.php).

#addNamespace($namespace, $hint)

The addNamespace method is responsible for adding a given $namespace to the loader. Each namespace requires a $hint. The $namespace parameter is used to give a name to the namespace, which typically would correspond to a package name, or some other logical organization. The $hint tells the framework where the locale and group files are located for the given namespace. For example, if a directory '/storage/lang_custom/' existed for storing custom language files, the directory path would become the $hint.

#Translation Namespaces

To prevent conflicts between multiple vendors using the same group names for a particular locale, the translator component allows the usage of "namespaces". Namespaces are a way to refer to a specific collection of locales and groups, where collection here refers to a different location on the file system. There is no limit on the number of namespaces that can be created. The translator component always has a * namespace available.

The * namespace refers to any groups that exist within the default /resources/lang directory. Namespaces are separated from the group and language line with the :: character sequence. Because of this, both function calls in the following example will return the same result:

 1<?php
 2
 3// The following function calls are assuming the 'en' locale, using
 4// the default Laravel translation groups.
 5
 6// Retrieving a language value without a namespace.
 7$passwordReset = trans('passwords.reset');
 8
 9// Retrieving a language value with the default namespace.
10$passwordResetTwo = trans('*::passwords.reset');

After the above code is executed, both $passwordReset and $passwordResetTwo would contain the same Your password has been reset! value.

Adding custom namespaces is simple. Assuming the directory /storage/lang_custom/ exists, it could be added to the file loader like so:

1<?php
2
3$loader = app('translation.loader');
4$loader->addNamespace('custom', storage_path('lang_custom'));

Assuming there was a locale directory en with the following passwords.php group file:

1<?php
2
3return [
4
5    'reset' => 'This is a custom reset message.',
6
7];

The value for reset can be retrieved from the custom namespace like so:

1<?php
2
3$defaultReset = trans('password.reset');
4$customReset  = trans('custom::password.reset');

After the above code is executed, the $defaultReset variable would have the value Your password has been reset! and the value of $customReset would be This is a custom reset message..

∎