Locale - Jet\Locale

The ability to create projects in different localizations (that is, intended for multiple languages and also regions/countries/states) is one of the important features and basic features of the Jet platform. It is based on the fact that I have "met" a number of such projects on my work journey. And I gained knowledge thanks to successes, but also failures and mistakes, or dead ends. That's why this feature is so important and permeates the entire system. It is one of the cornerstones of MVC , but localization is even a separate data type in ORM DataModel . Therefore, I include this topic as one of the first chapters. But enough talk... It comes down to business.

Localization? Why not language, or language mutation?

Why don't I simply use the term language mutation, language, or something like that? I mentioned failures in the introduction, and it was not by chance. One of those failures was precisely that I thought that the distinction by language would be enough and thus built a CMS. My naivety was punished and cured very soon. A project came along that included a lot of countries and a lot of language mutations. The content was meant to be linked and shared to a large extent. I was glad how prepared we are for such a project. When we came across such a "trifle". That even the German in Austria is not exactly the same German as in Germany... I'm not even talking about American and British English. And then we usually have countries where they don't use one language, but two or more. Switzerland, Belgium, Canada... And after all, our former Czechoslovakia...
Tying something purely to a language is simply not enough. Language is not one and it is not just a language. It is also about displaying numbers, prices, dates and times... It's just a topic in itself. That's pretty obvious, isn't it? But it just didn't occur to me years ago... But now I know. Therefore, Jet strictly uses the concept of localization and works with the Locale entity.

What does Locale look like in Jet?

Nothing special ... This is the identifier used by the ICU . It is a string consisting of two codes separated by the character "_".

For example, ours: cs_CZ

The first code is the ISO 639 language code (cs - Czech)

The second code is the ISO 3166 country code (CZ - Czech Republic / Czechia)

Attention! In fact, there may be even more information within this code. It concerns e.g. Chinese and the like. To be honest, I haven't used this aspect in practice yet, but it is one of the reasons why the system does not 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're not working with text, but with an instance of that class. In the future, I assume that Jet\Locale will expand even more based on practical knowledge - perhaps just knowledge from you - colleagues. But the basis is to have a fixed order and system in the application, and that system says that the localization code according to ISO standards is used, but always in the form of a Jet\Locale instance.

Jet\Locale class

As you already know, the localization code in the form of a text string is not used in the system, but everything that works with localization expects an instance of this class. So it is a relatively small, isolated class, but it is all the more important. Let's take a look at her. What is its purpose?

Its instance represents information about a specific location. Thus, an instance of this class is used everywhere as the primary localization identifier.
It is also a facade over a number of features already integrated into PHP itself.
Allows you to conveniently format numbers, time data and prices.
Allows you to work with localization as such. For example, to get the exact name of a given location, perhaps even in another location (see below)

And now let's look at the class itself. We will divide the methods according to whether they are intended for general use (they will be static methods) and methods related to a specific localization - non-static.

Non-static methods - work with specific localization

Method	Importance
public __construct ( string\|null $locale = null )	As a parameter of the constructor, the localization text code according to ISO standards can be (and in practice usually is) passed. So, for example "cs_CZ", but of course any other. If so, then this code is automatically parsed and the object is set. The public static method \Locale::parseLocale(string $locale): ?array of PHP itself is used for parsing. As already mentioned, the Jet\Locale class represents a facade on top of things that PHP already includes by default. Specifically, it is an Intl module. This has been taken as standard since long ago PHP5.3 and is therefore simply counted on.
public getRegion ( ): string	Returns the ISO 3166 two-digit region (or country if you prefer) code.
public getLanguage ( ): string	Returns the ISO 639 language code
public getName ( Locale\|null $in_locale = null ): string	Returns the end-user readable full name of the locale. For example, "Czech (Czech Republic)" for cs_CZ localization. The $in_locale parameter specifies the locale in which the name should be returned. Thus, it is possible to obtain the cs_CZ localization name, which is 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 end-user readable full name of the language. 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 obtain the cs_CZ language name, which is readable for the USA, i.e. for the en_US localization. Then the method returns: "Czech" If the parameter is not specified, then the current localization is used.
public getRegionName ( Locale\|null $in_locale = null ): string	Returns the end-user readable full name of the country - region. For example, "Czechia" for cs_CZ. The $in_locale parameter specifies the locale in which the name should be returned. Thus, it is possible to obtain the cs_CZ language name, which is readable for the USA, i.e. for the en_US localization. Then the method returns: "Czechia" If the parameter is not specified, then the current localization is used.
public getTimeZone ( ): string	Returns the time zone code. Attention! The value is not set by the constructor, for example. Which time zone will be used for a given localization depends on you and the situation. It does not always have to be the case that the used localization = time zone. In addition, large countries are in several time zones. So the time zone is not a definite thing. The default is the time zone set by PHP, i.e. the server. However, for example, in the initializer when using MVC, you can set the current location to the time zone according to your needs.
public setTimeZone ( string $time_zone ): void	Sets the localization time zone. See the previous getTimeZone method for more.
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. So, which calendar will be used depends on many factors, a specific project, a specific situation and a specific application. Thus, just as with the time zone, it is possible to set the calendar (see the getTimeZone method) The calendar types are Jet\Locale::CALENDAR_GREGORIAN and Jet\Locale::CALENDAR_TRADITIONAL, but again this is a facade over PHP .
public setCalendar ( int $calendar ): void	Sets the calendar used. See the previous getCalendar method for more.
public getLocale (): string	S lokalizací je pochopitelně někde nutné pracovat opět jako s řetězcem. Například při ukládání tohoto údaje - ať už do databáze, nebo do souboru. Za tímto účelem tyto metody vrací textový kód lokalizace. Instanci Jet\Locale tedy lze přetypovat na string.
public __toString (): string
public toString (): string
public formatDate ( ?Data_DateTime $date_and_time, int $format = self::DATE_TIME_FORMAT_MEDIUM ): string	It returns the date formatted according to the conventions valid for the given localization. See constants for possible formats.
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 the date and time formatted according to the conventions valid for the given localization. See constants for possible formats.
public formatTime ( ?Data_DateTime $date_and_time, int $time_format = self::DATE_TIME_FORMAT_SHORT ): string	Returns the time formatted according to the customs valid for the given localization. See constants for possible formats.
public formatInt ( int $number ): string	Returns an integer formatted according to locale conventions.
public formatFloat ( float $number, int $min_fraction_digits = 0, int $max_fraction_digits = 2 ): string	Returns a decimal number formatted according to locale conventions. 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 data volume (e.g. file size) formatted according to the customs applicable for the given localization.
public formatCurrency ( float\|int $value, string $currency ) : string	Returns the amount formatted according to the customs valid for the given localization and in the given currency. The currency is determined by the code according to ISO 4217 . (Currency is also not strongly tied to localization)
public getCurrencyFormatter ( string $currency ): \NumberFormatter	Returns a PHP instance of the \NumberFormatter class initialized so that it is ready to format numbers in the given locale and currency. The currency is determined by the code according to ISO 4217 .

Static methods - general

Method	Importance
public static getCurrentLocale ( ): Local	Returns an instance of the currently valid (currently cast) locale.
public static setCurrentLocale ( Locale $current_locale ): void	Sets the currently valid localization. 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	Jedná se o zkratku pro:`Locale::getCurrentLocale()->formatDate( $date_and_time, $format );` Stačí tedy: `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	Jedná se o zkratku pro:`Locale::getCurrentLocale()->formatDateAndTime( $date_and_time, $date_format, $time_format );` Stačí tedy: `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	Jedná se o zkratku pro:`Locale::getCurrentLocale()->formatTime( $date_and_time, $time_format );` Stačí tedy: `Locale::dateAndTime( $date_and_time, $time_format );`
public static int ( int $number ): string	Jedná se o zkratku pro:`Locale::getCurrentLocale()->formatInt( $number );` Stačí tedy: `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 );` Stačí tedy: `Locale::float( $number, $min_fraction_digits, $max_fraction_digits );`
public static size ( int $bytes, string $unit = 'iB', int $max_places = 2, string $glue = ' ' ): string	Jedná se o zkratku pro:`Locale::getCurrentLocale()->formatSize( $bytes, $unit, $max_places, $glue );` Stačí tedy: `Locale::size( $bytes, $unit, $max_places, $glue );`
public static currency ( float\|int $value, string $currency ): string	Jedná se o zkratku pro:`Locale::getCurrentLocale()->formatCurrency( $value, $currency );` Stačí tedy: `Locale::currency( $value, $currency );`
public static getAllLocalesList ( null\|Locale $in_locale = null ) : array	Returns all known locations or their names. The output is an array where the key is the locale code and the value is the locale name. The $in_locale parameter can be used to determine which localization the location names will be in. The default is the current location.

Constants

Constant	Importance
Jet\Locale::CALENDAR_GREGORIAN	Corresponds to the PHP constant \IntlDateFormatter::GREGORIAN
Jet\Locale::CALENDAR_TRADITIONAL	Corresponds to the PHP constant \IntlDateFormatter::TRADITIONAL
Jet\Locale::DATE_TIME_FORMAT_SHORT	Corresponds to the PHP constant \IntlDateFormatter::SHORT
Jet\Locale::DATE_TIME_FORMAT_MEDIUM	Corresponds to the PHP constant \IntlDateFormatter::MEDIUM
Jet\Locale::DATE_TIME_FORMAT_LONG	Corresponds to the PHP constant \IntlDateFormatter::LONG
Jet\Locale::DATE_TIME_FORMAT_FULL	Corresponds to the PHP constant \IntlDateFormatter::FULL