Locale guide

Search…
Locale guide
The Locale module provides a mechanism to build apps that adapt to users using different languages, timezones, currencies and other local unit standards.
To allow your app to work with different languages and localization settings, you must at least set up the availableLocales, defaultLocale, canonicalLocale and availableLanguages configuration keys in the config/Locale.config.php file like this:
1
<?php
2
​
3
namespace Cherrycake;
4
​
5
$LocaleConfig = [
6
	"availableLocales" => [
7
		"main" => [
8
			"language" => LANGUAGE_ENGLISH,
9
			"dateFormat" => DATE_FORMAT_MIDDLE_ENDIAN,
10
			"temperatureUnits" => TEMPERATURE_UNITS_FAHRENHEIT,
11
			"currency" => CURRENCY_USD,
12
			"decimalMark" => DECIMAL_MARK_POINT,
13
			"measurementSystem" => MEASUREMENT_SYSTEM_IMPERIAL,
14
			"timeZone" => TIMEZONE_ID_ETC_UTC
15
		]
16
	],
17
	"defaultLocale" => "main",
18
	"canonicalLocale" => "main",
19
	"availableLanguages" => [LANGUAGE_ENGLISH]
20
];
Copied!
availableLocales The different localizations your app will support. See the Locale configuration for an explanation of the available options.
defaultLocale The name of the locale to use as default.
canonicalLocale The name of the locale to be considered the main locale of the app.
availableLanguages An array of the languages that will be available in the app, from the available LANGUAGE_? constants.
If you don't setup your own availableLocales, or if you don't create a Locale configuration file at all,  a default locale named main will be used with the default configuration values.
Once your availableLocales are in place, you can choose the locale to use by calling the Locale::setLocale method. From that point on, all the texts, dates, timezones and other localized data will be retrieved using that locale's setup. For example:
1
echo $e->Locale->formatTimestamp(time());
2
echo $e->Locale->formatCurrency(19.5);
3
echo $e->Locale->getTimeZoneName();
Copied!
1
5/18/20
2
USD19.50
3
Etc/UTC
Copied!
Multiple locales
If your app supports multiple localized versions with different languages or localization configurations, you just add more locales to your Locale.config.php file. Imagine we have a web site with a global version in english, and a local version for Spain:
1
<?php
2
​
3
namespace Cherrycake;
4
​
5
$LocaleConfig = [
6
	"availableLocales" => [
7
		"global" => [
8
			"language" => LANGUAGE_ENGLISH,
9
			"dateFormat" => DATE_FORMAT_MIDDLE_ENDIAN,
10
			"temperatureUnits" => TEMPERATURE_UNITS_FAHRENHEIT,
11
			"currency" => CURRENCY_USD,
12
			"decimalMark" => DECIMAL_MARK_POINT,
13
			"measurementSystem" => MEASUREMENT_SYSTEM_IMPERIAL,
14
			"timeZone" => TIMEZONE_ID_ETC_UTC
15
		],
16
		"spain" => [
17
			"language" => LANGUAGE_SPANISH,
18
			"dateFormat" => DATE_FORMAT_LITTLE_ENDIAN,
19
			"temperatureUnits" => TEMPERATURE_UNITS_CELSIUS,
20
			"currency" => CURRENCY_EURO,
21
			"decimalMark" => DECIMAL_MARK_COMMA,
22
			"measurementSystem" => MEASUREMENT_SYSTEM_METRIC,
23
			"timeZone" => TIMEZONE_ID_EUROPE_MADRID
24
		]
25
	],
26
	"defaultLocale" => "global",
27
	"canonicalLocale" => "global",
28
	"availableLanguages" => [LANGUAGE_ENGLISH, LANGUAGE_SPANISH]
29
];
Copied!
Now, we can switch the working locale whenever we need, and Locale will act accordingly:
1
echo $e->Locale->formatTimestamp(time());
2
echo $e->Locale->formatCurrency(19.5);
3
echo $e->Locale->getTimeZoneName();
4
​
5
$e->Locale->setLocale("spain");
6
​
7
echo $e->Locale->formatTimestamp(time());
8
echo $e->Locale->formatCurrency(19.5);
9
echo $e->Locale->getTimeZoneName();
Copied!
1
5/18/20
2
USD19.50
3
Etc/UTC
4
​
5
18/5/20
6
19,50€
7
Europe/Madrid
Copied!
See this example working in the Cherrycake documentation examples site.
Creating a complete login workflow
Multilingual texts
Last modified 2yr ago
Copy link
Contents
Multiple locales