Localization

Working With Locales

CodeIgniter provides several tools to help you localize your application for different languages. While fulllocalization of an application is a complex subject, it’s simple to swap out strings in your applicationwith different supported languages.

Language strings are stored in the app/Language directory, with a sub-directory for eachsupported language:

  1. /app
  2.     /Language
  3.         /en
  4.             app.php
  5.         /fr
  6.             app.php

Important

Locale detection only works for web-based requests that use the IncomingRequest class.Command-line requests will not have these features.

Configuring the Locale

Every site will have a default language/locale they operate in. This can be set in Config/App.php:

  1. public $defaultLocale = 'en';

The value can be any string that your application uses to manage text strings and other formats. It isrecommended that a BCP 47 language code is used. This results inlanguage codes like en-US for American English, or fr-FR, for French/France. A more readable introductionto this can be found on the W3C’s site.

The system is smart enough to fall back to more generic language codes if an exact matchcannot be found. If the locale code was set to en-US and we only have language files set up for enthen those will be used since nothing exists for the more specific en-US. If, however, a languagedirectory existed at app/Language/en-US then that would be used first.

Locale Detection

There are two methods supported to detect the correct locale during the request. The first is a “set and forget”method that will automatically perform content negotiation for you todetermine the correct locale to use. The second method allows you to specify a segment in your routes thatwill be used to set the locale.

Content Negotiation

You can set up content negotiation to happen automatically by setting two additional settings in Config/App.The first value tells the Request class that we do want to negotiate a locale, so simply set it to true:

  1. public $negotiateLocale = true;

Once this is enabled, the system will automatically negotiate the correct language based upon an arrayof locales that you have defined in $supportLocales. If no match is found between the languagesthat you support, and the requested language, the first item in $supportedLocales will be used. Inthe following example, the en locale would be used if no match is found:

  1. public $supportedLocales = ['en', 'es', 'fr-FR'];

In Routes

The second method uses a custom placeholder to detect the desired locale and set it on the Request. Theplaceholder {locale} can be placed as a segment in your route. If present, the contents of the matchingsegment will be your locale:

  1. $routes->get('{locale}/books', 'App\Books::index');

In this example, if the user tried to visit http://example.com/fr/books, then the locale would beset to fr, assuming it was configured as a valid locale.

Note

If the value doesn’t match a valid locale as defined in the App configuration file, the defaultlocale will be used in it’s place.

Retrieving the Current Locale

The current locale can always be retrieved from the IncomingRequest object, through the getLocale() method.If your controller is extending CodeIgniter\Controller, this will be available through $this->request:

  1. <?php namespace App\Controllers;
  2.  
  3. class UserController extends \CodeIgniter\Controller
  4. {
  5.     public function index()
  6.     {
  7.         $locale = $this->request->getLocale();
  8.     }
  9. }

Alternatively, you can use the Services class to retrieve the current request:

  1. $locale = service('request')->getLocale();

Language Localization

Creating Language Files

Languages do not have any specific naming convention that are required. The file should be named logically todescribe the type of content it holds. For example, let’s say you want to create a file containing error messages.You might name it simply: Errors.php.

Within the file, you would return an array, where each element in the array has a language key and the string to return:

  1. 'language_key' => 'The actual message to be shown.'

Note

It’s good practice to use a common prefix for all messages in a given file to avoid collisions withsimilarly named items in other files. For example, if you are creating error messages you might prefix themwith error_

  1. return [
  2.     'errorEmailMissing'    => 'You must submit an email address',
  3.     'errorURLMissing'      => 'You must submit a URL',
  4.     'errorUsernameMissing' => 'You must submit a username',
  5. ];

Basic Usage

You can use the lang() helper function to retrieve text from any of the language files, by passing thefilename and the language key as the first parameter, separated by a period (.). For example, to load theerrorEmailMissing string from the Errors language file, you would do the following:

  1. echo lang('Errors.errorEmailMissing');

If the requested language key doesn’t exist in the file for the current locale, the string will be passedback, unchanged. In this example, it would return ‘Errors.errorEmailMissing’ if it didn’t exist.

Replacing Parameters

Note

The following functions all require the intl extension tobe loaded on your system in order to work. If the extension is not loaded, no replacement will be attempted.A great overview can be found over at Sitepoint.

You can pass an array of values to replace placeholders in the language string as the second parameter to thelang() function. This allows for very simple number translations and formatting:

  1. // The language file, Tests.php:
  2. return [
  3.     "apples"      => "I have {0, number} apples.",
  4.     "men"         => "I have {1, number} men out-performed the remaining {0, number}",
  5.     "namedApples" => "I have {number_apples, number, integer} apples.",
  6. ];
  7.  
  8. // Displays "I have 3 apples."
  9. echo lang('Tests.apples', [ 3 ]);

The first item in the placeholder corresponds to the index of the item in the array, if it’s numerical:

  1. // Displays "The top 23 men out-performed the remaining 20"
  2. echo lang('Tests.men', [20, 23]);

You can also use named keys to make it easier to keep things straight, if you’d like:

  1. // Displays "I have 3 apples."
  2. echo lang("Tests.namedApples", ['number_apples' => 3]);

Obviously, you can do more than just number replacement. According to theofficial ICU docs for the underlyinglibrary, the following types of data can be replaced:

  • numbers - integer, currency, percent
  • dates - short, medium, long, full
  • time - short, medium, long, full
  • spellout - spells out numbers (i.e. 34 becomes thirty-four)
  • ordinal
  • duration

Here are a few examples:

  1. // The language file, Tests.php
  2. return [
  3.     'shortTime'  => 'The time is now {0, time, short}.',
  4.     'mediumTime' => 'The time is now {0, time, medium}.',
  5.     'longTime'   => 'The time is now {0, time, long}.',
  6.     'fullTime'   => 'The time is now {0, time, full}.',
  7.     'shortDate'  => 'The date is now {0, date, short}.',
  8.     'mediumDate' => 'The date is now {0, date, medium}.',
  9.     'longDate'   => 'The date is now {0, date, long}.',
  10.     'fullDate'   => 'The date is now {0, date, full}.',
  11.     'spelledOut' => '34 is {0, spellout}',
  12.     'ordinal'    => 'The ordinal is {0, ordinal}',
  13.     'duration'   => 'It has been {0, duration}',
  14. ];
  15.  
  16. // Displays "The time is now 11:18 PM"
  17. echo lang('Tests.shortTime', [time()]);
  18. // Displays "The time is now 11:18:50 PM"
  19. echo lang('Tests.mediumTime', [time()]);
  20. // Displays "The time is now 11:19:09 PM CDT"
  21. echo lang('Tests.longTime', [time()]);
  22. // Displays "The time is now 11:19:26 PM Central Daylight Time"
  23. echo lang('Tests.fullTime', [time()]);
  24.  
  25. // Displays "The date is now 8/14/16"
  26. echo lang('Tests.shortDate', [time()]);
  27. // Displays "The date is now Aug 14, 2016"
  28. echo lang('Tests.mediumDate', [time()]);
  29. // Displays "The date is now August 14, 2016"
  30. echo lang('Tests.longDate', [time()]);
  31. // Displays "The date is now Sunday, August 14, 2016"
  32. echo lang('Tests.fullDate', [time()]);
  33.  
  34. // Displays "34 is thirty-four"
  35. echo lang('Tests.spelledOut', [34]);
  36.  
  37. // Displays "It has been 408,676:24:35"
  38. echo lang('Tests.ordinal', [time()]);

You should be sure to read up on the MessageFormatter class and the underlying ICU formatting to get a betteridea on what capabilities it has, like performing the conditional replacement, pluralization, and more. Both of the links providedearlier will give you an excellent idea as to the options available.

Specifying Locale

To specify a different locale to be used when replacing parameters, you can pass the locale in as thethird parameter to the lang() method.

  1. // Displays "The time is now 23:21:28 GMT-5"
  2. echo lang('Test.longTime', [time()], 'ru-RU');
  3.  
  4. // Displays "£7.41"
  5. echo lang('{price, number, currency}', ['price' => 7.41], 'en-GB');
  6. // Displays "$7.41"
  7. echo lang('{price, number, currency}', ['price' => 7.41], 'en-US');

Nested Arrays

Language files also allow nested arrays to make working with lists, etc… easier.

  1. // Language/en/Fruit.php
  2.  
  3. return [
  4.     'list' => [
  5.         'Apples',
  6.         'Bananas',
  7.         'Grapes',
  8.         'Lemons',
  9.         'Oranges',
  10.         'Strawberries'
  11.     ]
  12. ];
  13.  
  14. // Displays "Apples, Bananas, Grapes, Lemons, Oranges, Strawberries"
  15. echo implode(', ', lang('Fruit.list'));

Language Fallback

If you have a set of messages for a given locale, for instanceLanguage/en/app.php, you can add language variants for that locale,each in its own folder, for instance Language/en-US/app.php.

You only need to provide values for those messages that would belocalized differently for that locale variant. Any missing messagedefinitions will be automatically pulled from the main locale settings.

It gets better - the localization can fall all the way back to English,in case new messages are added to the framework and you haven’t hada chance to translate them yet for your locale.

So, if you are using the locale fr-CA, then a localizedmessage will first be sought in Language/fr/CA, then inLanguage/fr, and finally in Language/en.

Message Translations

We have an “official” set of translations in theirown repository.

You could download that repository, and copy its Language folderinto your app. The incorporated translations will be automaticallypicked up because the App namespace is mapped to your app folder.

Alternately, a better practice would be to composer require codeigniter4/translationsinside your project, and the translated messages will be automatically pickedup because the translations folders get mapped appropriately.