Locale - Jet\Locale
The ability to create projects in different localizations (i.e. for multiple languages and regions/countries/countries) is one of the important features and basic characteristics of the Jet platform. This is based on the fact that I have "met" a number of such projects during my work journey. And I have gained knowledge through successes, but also failures and mistakes or dead ends. That is why this feature is so important and permeates the whole system. It's one of the cornerstones of MVC, but localization is even a separate data type in ORM DataModel. That's why I'm including this topic as one of the first chapters. But enough talk ... Let's get down to business.
Localization? Why not a language or a language mutation?
Why don't I simply use the term language mutation, language, or something like that? I mentioned setbacks in my introduction, and not by accident. One of those failures was just about the fact that I thought that differentiation by language would be enough and built a CMS that way. My naivety was punished and cured very soon. A project came along that involved a lot of countries and a lot of languages. The content was to be largely linked and shared. I rejoiced at how prepared we were for such a project. Until we came across this "little thing". That even the German in Austria is not quite the same German as in Germany ... Not to mention American and British English. And then we normally have countries where they don't use one language, but two or more. Switzerland, Belgium, Canada ... And our former Czechoslovakia...
What does Locale look like in Jet?
Nothing special ... It is an identifier used by the ICU. It is a string consisting of two codes separated by a "_" character.
For example, ours is: cs_CZ
The first code is the ISO 639 code for the language (cs - Czech)
The second code is the ISO 3166 code for the country (CZ - Czech Republic / Czechia)
Warning! There may actually be more information within this code. It relates to e.g. Chinese and so on. In truth, I haven't used this aspect in practice, but it's one of the reasons why the system doesn't use code in the form of a text string, but an instance of the Jet\Locale class. This is very important! When you pass a Locale somewhere, you are not working with text, but an instance of that class. In the future, I expect that Jet\Locale will be extended based on practical knowledge - maybe just knowledge from you - colleagues. But the basic thing is to have a fixed order and system in the application, and that system says that you use the localization code according to ISO standards, but always in the form of an instance of Jet\Locale.
Jet\Locale class
As you already know, the system does not use localization code in the form of a text string, but everything that works with localization expects an instance of this class. So it's a relatively small, solitary, but all the more important class. Let's take a look at it. What is its purpose?
- Their instance represents information about a specific location. That is, an instance of this class is used everywhere as the primary identifier of a locale.
- It is also a facade over a number of functions already integrated in PHP itself.
- It allows convenient formatting of numbers, times and prices.
- It allows working with the locale itself. For example, to get the exact name of a given localization, even in another localization (see below)
Now let's look at the class itself. We will divide the methods according to whether they are intended for general use (that will be static methods) and methods related to a specific location - non-static.
Nestatic methods - working with a specific location
| Metoda |
Význam |
public __construct(
string|null $locale = null
) | The text code of localization according to ISO standards can be (and usually is) passed as a constructor parameter. So for example "en_CZ", but of course any other. If this is the case, then this code is automatically parsed and the object is set.
The parsing is done using the public static \Locale::parseLocale(string $locale): ?array method of PHP itself.
As already mentioned, the Jet\Locale class is a facade over things that PHP already includes by default. Specifically, the Intl module. This has been taken as standard since PHP5.3, and thus is simply expected. |
public getRegion(
): string | Returns the two-digit region (or country) code according to ISO 3166. |
public getLanguage(
): string |
Returns language code according to ISO 639 |
public getName(
Locale|null $in_locale = null
): string |
Returns the full name of the localization legible to the end user.
For example, "Czech (Czech Republic)" for localization cs_CZ.
The $in_locale parameter specifies the localization name to return.
Thus, it is possible to get the name of the cs_CZ localization but readable for the USA, i.e. for the en_US localization. Then the method returns "Czech (Czechia)"
If the parameter is not specified, then the current localization is used. |
public getLanguageName(
Locale|null $in_locale = null
): string |
Returns the full language name readable to the end user.
For example, "Czech" for cs_CZ.
The $in_locale parameter specifies the locale in which the name should be returned.
Thus, it is possible to get the language name cs_CZ but readable for the US, i.e. for the en_US locale. Then the method will return "Czech"
If the parameter is not specified, then the current localization is used. |
public getRegionName(
Locale|null $in_locale = null
): string |
Returns the full name of the country-region legible to the end user.
For example, "Czech Republic" for en_CZ.
The $in_locale parameter specifies the locale in which the name should be returned.
Thus, it is possible to get the name of the language cs_CZ but readable for the USA, i.e. for the localization en_US. Then the method will return "Czechia"
If the parameter is not specified, then the current localization is used. |
public getTimeZone(
): string |
Returns the time zone code.
Warning! The value is not set, for example, by the constructor. What time zone is used for a given location depends on you and the situation. It may not always be true that the localization used = time zone. Moreover, large countries are in several time zones. Thus, the time zone is not a clear-cut thing.
The default time zone is the one that PHP, or the server, has set as default. However, for example, in initializer when using MVC you can set the current localization time zone to your needs. |
public setTimeZone(
string $time_zone
): void |
Sets the time zone localization. See the previous method getTimeZone. |
public getCalendar(
): int |
Returns the number of the used calendar. The default is the Gregorian calendar.
But the situation is analogous to the time zone. Thus, what calendar is used depends on many factors, the specific project, the specific situation, and the specific application.
Thus, just like with a time zone, you can set the calendar (see the getTimeZone method )
The types of calendars are Jet\Locale::CALENDAR_GREGORIAN and Jet\Locale::CALENDAR_TRADITIONAL, but this is again a over PHP facade. |
public setCalendar(
int $calendar
): void |
Sets the calendar used. See the previous method getCalendar. |
| public getLocale(): string |
It is of course necessary to work with localization as a string again. For example, when storing this data - either in a database or in a file.
To this end, these methods return the text code of the localization. Thus, an instance of Jet\Locale can be mapped to a string. |
| public __toString(): string |
| public toString(): string |
public formatDate(
?Data_DateTime $date_and_time,
int $format = self::DATE_TIME_FORMAT_MEDIUM
): string |
Returns the date formatted according to the conventions valid for the given localization.
For possible formats see constants. |
public formatDateAndTime(
?Data_DateTime $date_and_time,
int $date_format = self::DATE_TIME_FORMAT_MEDIUM,
int $time_format = self::DATE_TIME_FORMAT_SHORT
): string |
Returns date and time formatted according to the conventions valid for the given localization.
For possible formats see constants. |
public formatTime(
?Data_DateTime $date_and_time,
int $time_format = self::DATE_TIME_FORMAT_SHORT
): string |
Returns the time formatted according to the conventions valid for the given localization.
For possible formats see constants. |
public formatInt(
int $number
): string |
Returns an integer formatted according to the conventions valid for the given locale. |
public formatFloat(
float $number,
int $min_fraction_digits = 0,
int $max_fraction_digits = 2
): string |
Returns a decimal number formatted according to the conventions valid for the given location.
It is possible to specify the minimum and maximum number of decimal places. |
public formatSize(
int $bytes,
string $unit = 'iB',
int $max_places = 2,
string $glue = ' '
): string |
Returns the data volume (e.g. file size) formatted according to the conventions valid for the given locale. |
public formatCurrency(
float|int $value,
string $currency
) : string |
Returns the amount formatted according to the conventions applicable to the locale and currency.
Currency is determined by the ISO 4217 encoding.
(Currency is also not fixed to the locale) |
public getCurrencyFormatter(
string $currency
): \NumberFormatter |
Returns an instance of the PHP class \NumberFormatter initialized to be ready to format numbers in the given locale and currency.
The currency is determined by the ISO 4217 codebase. |
Static Methods - General
| Metoda |
Meaning of |
public static getCurrentLocale(
): Locale |
Returns an instance of the currently valid (currently set) localization. |
public static setCurrentLocale(
Locale $current_locale
): void |
Sets the currently valid locale.
If you use Jet MVC, the router will do this for you.
Otherwise (if you don't use Jet MVC) you need to set the current locale. |
public static date(
?Data_DateTime $date_and_time,
int $format = self::DATE_TIME_FORMAT_MEDIUM
): string |
This is a shorthand for:
Locale::getCurrentLocale()->formatDate( $date_and_time, $format );
You can use:
Locale::date( $date_and_time, $format );
|
public static dateAndTime(
?Data_DateTime $date_and_time,
int $date_format = self::DATE_TIME_FORMAT_MEDIUM,
int $time_format = self::DATE_TIME_FORMAT_SHORT
): string |
This is a shorthand for:
Locale::getCurrentLocale()->formatDateAndTime( $date_and_time, $date_format, $time_format );
You can use:
Locale::dateAndTime( $date_and_time, $date_format, $time_format );
|
public static time(
?Data_DateTime $date_and_time,
int $time_format = self::DATE_TIME_FORMAT_SHORT
): string |
This is a shorthand for:
Locale::getCurrentLocale()->formatTime( $date_and_time, $time_format );
You can use:
Locale::dateAndTime( $date_and_time, $time_format );
|
public static int(
int $number
): string |
This is a shorthand for:
Locale::getCurrentLocale()->formatInt( $number );
You can use:
Locale::int( $number );
|
public static float(
float $number,
int $min_fraction_digits = 0,
int $max_fraction_digits = 2
): string |
Jedná se o zkratku pro:
Locale::getCurrentLocale()->formatFloat( $number, $min_fraction_digits, $max_fraction_digits );
You can use:
Locale::float( $number, $min_fraction_digits, $max_fraction_digits );
|
public static size(
int $bytes, string $unit = 'iB',
int $max_places = 2,
string $glue = ' '
): string |
This is a shorthand for:
Locale::getCurrentLocale()->formatSize( $bytes, $unit, $max_places, $glue );
You can use:
Locale::size( $bytes, $unit, $max_places, $glue );
|
public static currency(
float|int $value,
string $currency
): string |
This is a shorthand for:
Locale::getCurrentLocale()->formatCurrency( $value, $currency );
You can use:
Locale::currency( $value, $currency );
|
public static getAllLocalesList(
null|Locale $in_locale = null
) : array |
Returns all known localizations, or their names.
The output is an array where the key is the localization code and the value is the localization name.
The $in_locale parameter can be used to specify which localization the localization names will be in. The default is the current locale. |
Konstanty
