Компонент Intl

Дата оновлення перекладу 2024-05-03

Компонент Intl

Цей компонент надає доступ до даних локалізації бібліотеки ICU.

See also

Ця стаття пояснює яка використовувати функції Intl в якості незалежного компонента у будь-якому додатку PHP. Прочитайте статтю Переклади для розуміння, як робити інтернаціоналізацію та управляти користувацькими локалями у додатках Symfony.

Установка

1
$ composer require symfony/intl

Note

Якщо ви встановлюєте цей компонент поза додатком Symfony, вам потрібно підключити файл vendor/autoload.phpу вашому коді для включення механізму автозавантаження класів, наданих Composer. Детальніше можна прочитати у цій статті.

Доступ до даних ICU

Цей компонент надає наступні дані ICU:

Мова та назви скриптів

Клас Languages надає доступ до назв усіх мов, відповідно до списків ISO 639-1 alpha-2 і ISO 639-2 alpha-3 (2T):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
use Symfony\Component\Intl\Languages;

\Locale::setDefault('en');

$languages = Languages::getNames();
// ('languageCode' => 'languageName')
// => ['ab' => 'Abkhazian', 'ace' => 'Achinese', ...]

$languages = Languages::getAlpha3Names();
// ('languageCode' => 'languageName')
// => ['abk' => 'Abkhazian', 'ace' => 'Achinese', ...]

$language = Languages::getName('fr');
// => 'French'

$language = Languages::getAlpha3Name('fra');
// => 'French'

Всі методи приймають локаль перекладу в якості останнього необовʼязкового параметра, який за замовчуванням має значення поточної локалі:

1
2
3
4
5
6
7
8
9
10
11
$languages = Languages::getNames('de');
// => ['ab' => 'Abchasisch', 'ace' => 'Aceh', ...]

$languages = Languages::getAlpha3Names('de');
// => ['abk' => 'Abchasisch', 'ace' => 'Aceh', ...]

$language = Languages::getName('fr', 'de');
// => 'Französisch'

$language = Languages::getAlpha3Name('fra', 'de');
// => 'Französisch'

Якщо задана локаль не існує, методи запускають MissingResourceException. На додаток до виявлення виключення, ви також можете перевірити, чи є код заданої мови валідним:

1
$isValidLanguage = Languages::exists($languageCode);

Або, якщо у вас є код мови alpha3, який ви хочете перевірити:

1
$isValidLanguage = Languages::alpha3CodeExists($alpha3Code);

Ви можете перетворювати ці коди між дволітерними alpha2 і трилітерними alpha3 кодами:

1
2
3
$alpha3Code = Languages::getAlpha3Code($alpha2Code);

$alpha2Code = Languages::getAlpha2Code($alpha3Code);

Клас Scripts надає доступ до необовʼязкового чотирилітерного коду скрипта, який може дотримуватися коду мови, відповідно до реєстру Unicode ISO 15924 (наприклад, HANS в zh_HANS для спрощеної китайської, і HANT в zh_HANT для традиційної китайської):

1
2
3
4
5
6
7
8
9
10
use Symfony\Component\Intl\Scripts;

\Locale::setDefault('en');

$scripts = Scripts::getNames();
// ('scriptCode' => 'scriptName')
// => ['Adlm' => 'Adlam', 'Afak' => 'Afaka', ...]

$script = Scripts::getName('Hans');
// => 'Simplified'

Всі методи приймають локаль перекладу в якості останнього необовʼязкового параметра, який за замовчуванням має значення поточної локалі:

1
2
3
4
5
$scripts = Scripts::getNames('de');
// => ['Adlm' => 'Adlam', 'Afak' => 'Afaka', ...]

$script = Scripts::getName('Hans', 'de');
// => 'Vereinfacht'

Якщо заданий код скрипта не існує, методи викликають MissingResourceException. На додаток до виявлення виключення, ви також можете перевірити, чи є заданий код скрипта валідним:

1
$isValidScript = Scripts::exists($scriptCode);

Назви країн

Клас Countries надає доступ до назв усіх країн, віповідно до списків ISO 3166-1 alpha-2 і ISO 3166-1 alpha-3 офіційно визнаних країн та територій:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
use Symfony\Component\Intl\Countries;

\Locale::setDefault('en');

$countries = Countries::getNames();
// ('alpha2Code' => 'countryName')
// => ['AF' => 'Afghanistan', 'AX' => 'Åland Islands', ...]

$countries = Countries::getAlpha3Names();
// ('alpha3Code' => 'countryName')
// => ['AFG' => 'Afghanistan', 'ALA' => 'Åland Islands', ...]

$country = Countries::getName('GB');
// => 'United Kingdom'

$country = Countries::getAlpha3Name('NOR');
// => 'Norway'

Всі методи приймають локаль перекладу в якості останнього необовʼязкового параметра, який за замовчуванням має значення поточної локалі:

1
2
3
4
5
6
7
8
9
10
11
$countries = Countries::getNames('de');
// => ['AF' => 'Afghanistan', 'EG' => 'Ägypten', ...]

$countries = Countries::getAlpha3Names('de');
// => ['AFG' => 'Afghanistan', 'EGY' => 'Ägypten', ...]

$country = Countries::getName('GB', 'de');
// => 'Vereinigtes Königreich'

$country = Countries::getAlpha3Name('GBR', 'de');
// => 'Vereinigtes Königreich'

Якщо заданий код країни не існує, методи викликають MissingResourceException. На додаток до виявлення виключення, ви також можете перевірити, чи є заданий код країни валідним:

1
$isValidCountry = Countries::exists($alpha2Code);

Або, якщо у вас код країни alpha3, ви можете перевірити:

1
$isValidCountry = Countries::alpha3CodeExists($alpha3Code);

Ви можете перетворювати коди між дволітерними alpha2 і трилітерними alpha3 кодами:

1
2
3
$alpha3Code = Countries::getAlpha3Code($alpha2Code);

$alpha2Code = Countries::getAlpha2Code($alpha3Code);

Цифрові коди країн

ISO 3166-1 (числовий) стандарт визначає тризначний код країни для представлення країн, залежних територій та спеціальних областей географічного інтересу.

Основною перевагою над алфавітними кодами ISO 3166-1 (alpha-2 і alpha-3) є те, що ці цифрові коди не залежать від системи письма. Літерні коди використовують 26-літерний англійський алфавіт, який може бути недоступним або складним у використанні для людей і систем, що використовують нелатинську писемність (наприклад, арабську або японську).

Клас Countries надає доступ до таких цифрових кодів країн:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
use Symfony\Component\Intl\Countries;

\Locale::setDefault('en');

$numericCodes = Countries::getNumericCodes();
// ('alpha2Code' => 'numericCode')
// => ['AA' => '958', 'AD' => '020', ...]

$numericCode = Countries::getNumericCode('FR');
// => '250'

$alpha2 = Countries::getAlpha2FromNumeric('250');
// => 'FR'

$exists = Countries::numericCodeExists('250');
// => true

Локалі

Локаль - це комбінація мови, регіону та деяких параметрів, які визначають налаштування інтерфейсу користувача. Наприклад, "китайська" - це мова, а zh_Hans_MO - локаль для "китайської" (мови) + "спрощений" (скрипт) + "Макау Китай" (регіон). Клас Locales надає доступ до назв усіх локалей:

1
2
3
4
5
6
7
8
9
10
use Symfony\Component\Intl\Locales;

\Locale::setDefault('en');

$locales = Locales::getNames();
// ('localeCode' => 'localeName')
// => ['af' => 'Afrikaans', 'af_NA' => 'Afrikaans (Namibia)', ...]

$locale = Locales::getName('zh_Hans_MO');
// => 'Chinese (Simplified, Macau SAR China)'

Всі методи приймають локаль перекладу в якості останнього необовʼязкового параметра, який за замовчуванням має значення поточної локалі:

1
2
3
4
5
$locales = Locales::getNames('de');
// => ['af' => 'Afrikaans', 'af_NA' => 'Afrikaans (Namibia)', ...]

$locale = Locales::getName('zh_Hans_MO', 'de');
// => 'Chinesisch (Vereinfacht, Sonderverwaltungsregion Macau)'

Якщо заданий код не існує, методи викликають MissingResourceException. На додаток до виявлення виключення, ви також можете перевірити, чи є заданий код локалі валідним:

1
$isValidLocale = Locales::exists($localeCode);

Валюти

Клас Currencies надає доступ до назв усіх валют, а також до їх деякої інформації (символ, цифри після коми і т.д.):

1
2
3
4
5
6
7
8
9
10
11
12
13
use Symfony\Component\Intl\Currencies;

\Locale::setDefault('en');

$currencies = Currencies::getNames();
// ('currencyCode' => 'currencyName')
// => ['AFN' => 'Afghan Afghani', 'ALL' => 'Albanian Lek', ...]

$currency = Currencies::getName('INR');
// => 'Indian Rupee'

$symbol = Currencies::getSymbol('INR');
// => '₹'

Методи цифр після коми повертають кількість десяткових знаків для відображення при форматуванні чисел у цій валюті. В залежності від валюти, це значення може змінюватися, якщо число використовується у готівкових транзакціях або інших сценаріях (наприклад, бухгалтерії):

1
2
3
4
5
6
7
// Індійська рупія визначає однакове значення для обох
$fractionDigits = Currencies::getFractionDigits('INR');         // returns: 2
$cashFractionDigits = Currencies::getCashFractionDigits('INR'); // returns: 2

// Шведська крона визначає різні значення
$fractionDigits = Currencies::getFractionDigits('SEK');         // returns: 2
$cashFractionDigits = Currencies::getCashFractionDigits('SEK'); // returns: 0

Деякі валюти вимагають округлених до найближчого числа значень (наприклад, 5 центів). Це округлення може відрізнятися, якщо числа відформатовані для готівкових транзакцій або інших сценаріїв (наприклад, бухгалтерії):

1
2
3
4
5
6
7
8
9
// Індійська рупія визначає однакове значення для обох
$roundingIncrement = Currencies::getRoundingIncrement('INR');         // returns: 0
$cashRoundingIncrement = Currencies::getCashRoundingIncrement('INR'); // returns: 0

// Канадський долар визначає різні значення, так як вони позбавилися дрібних
// монет (в 1 і 2 центи), і ціни готівкою мають округлятися до 5 центів (наприклад,
// якщо ціна - 7.42, ви сплачуєте 7.40; якщо 7.48 - то 7.50)
$roundingIncrement = Currencies::getRoundingIncrement('CAD');         // returns: 0
$cashRoundingIncrement = Currencies::getCashRoundingIncrement('CAD'); // returns: 5

Всі методи, окрім getFractionDigits(), getCashFractionDigits(), getRoundingIncrement() і getCashRoundingIncrement() приймають локаль перекладу в якості останнього необовʼязкового параметра, який за замовчуванням є поточною локаллю:

1
2
3
4
5
$currencies = Currencies::getNames('de');
// => ['AFN' => 'Afghanischer Afghani', 'EGP' => 'Ägyptisches Pfund', ...]

$currency = Currencies::getName('INR', 'de');
// => 'Indische Rupie'

Якщо заданий код валюти не існує, методи викликають MissingResourceException. На додаток до виявлення виключення, ви також можете перевірити, чи є заданий код валюти валідним:

1
$isValidCurrency = Currencies::exists($currencyCode);

Часові пояси

Клас Timezones надає декілька утиліт, повʼязаних з часовими поясами. По-перше, ви можете отримати назву та значення усіх часових поясів усіма мовами:

1
2
3
4
5
6
7
8
9
10
use Symfony\Component\Intl\Timezones;

\Locale::setDefault('en');

$timezones = Timezones::getNames();
// ('timezoneID' => 'timezoneValue')
// => ['America/Eirunepe' => 'Acre Time (Eirunepe)', 'America/Rio_Branco' => 'Acre Time (Rio Branco)', ...]

$timezone = Timezones::getName('Africa/Nairobi');
// => 'East Africa Time (Nairobi)'

Всі методи приймають локаль перекладу в якості останнього необовʼязкового параметра, який за замовчуванням має значення поточної локалі:

1
2
3
4
5
$timezones = Timezones::getNames('de');
// => ['America/Eirunepe' => 'Acre-Zeit (Eirunepe)', 'America/Rio_Branco' => 'Acre-Zeit (Rio Branco)', ...]

$timezone = Timezones::getName('Africa/Nairobi', 'de');
// => 'Ostafrikanische Zeit (Nairobi)'

Ви також можете отримати всі існуючі часові пояси у заданій країні. Метод forCountryCode() повертає один або більше ID часових поясів, які ви можете перекласти на будь-яку локаль за допомогою методу getName(), продемонстрованого раніше:

1
2
3
// на відміну від кодів мов, коди країн завжди використвують верхній регістр (CL = Chile)
$timezones = Timezones::forCountryCode('CL');
// => ['America/Punta_Arenas', 'America/Santiago', 'Pacific/Easter']

Зворотний перегляд також можливий, завдяки методу getCountryCode(), який повертає код країни, якій належить ID заданого часового поясу:

1
2
$countryCode = Timezones::getCountryCode('America/Vancouver');
// => $countryCode = 'CA' (CA = Canada)

Зміщення часу UTC/GMT всіх часових поясів надається getRawOffset() (який повертає ціле число, що представляє собою зміщення часу у секундах) і getGmtOffset() (який повертає рядок, що представляє собою зміщення часу для відображення користувачам):

1
2
3
4
5
6
7
$offset = Timezones::getRawOffset('Etc/UTC');              // $offset = 0
$offset = Timezones::getRawOffset('America/Buenos_Aires'); // $offset = -10800
$offset = Timezones::getRawOffset('Asia/Katmandu');        // $offset = 20700

$offset = Timezones::getGmtOffset('Etc/UTC');              // $offset = 'GMT+00:00'
$offset = Timezones::getGmtOffset('America/Buenos_Aires'); // $offset = 'GMT-03:00'
$offset = Timezones::getGmtOffset('Asia/Katmandu');        // $offset = 'GMT+05:45'

Зміщення часу часового поясу може відрізнятися у часі через практику літнього часу (DST). За замовчуванням, ці методи використовують PHP-функцію time(), щоб отримати поточне значення зміщення часу часового поясу, але ви можете передати часову відмітку в якості других аргументів, щоб отримати зміщення часу у будь-який заданий період часу:

1
2
3
4
5
// У 2019, період літнього часу у Мадриді (Іспанія) проходив з 31 березня по 27 жовтня
$offset = Timezones::getRawOffset('Europe/Madrid', strtotime('March 31, 2019'));   // $offset = 3600
$offset = Timezones::getRawOffset('Europe/Madrid', strtotime('April 1, 2019'));    // $offset = 7200
$offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 27, 2019')); // $offset = 'GMT+02:00'
$offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 28, 2019')); // $offset = 'GMT+01:00'

Рядкова репрезентація зміщення часу GMT може відрізнятися в залежності від локалі, так що ви можете передати локаль в якості третього необовʼязкового аргументу:

1
2
$offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 28, 2019'), 'ar'); // $offset = 'غرينتش+01:00'
$offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 28, 2019'), 'dz'); // $offset = 'ཇི་ཨེམ་ཏི་+01:00'

Якщо заданий ID часового поясу не існує, методи викличуть MissingResourceException. На додаток до виявлення виключення, ви також можете перевірити, чи є заданий код часового поясу валідним:

1
$isValidTimezone = Timezones::exists($timezoneId);

Транслітерація емодзі

Symfony надає утиліти для перекладу емодзі в їхнє текстове представлення на всіх мовах. Прочитайте документацію про роботу з емодзі у рядках , щоб дізнатися більше про цю можливість.

Symfony provides utilities to translate emojis into their textual representation in all languages. Read the documentation on working with emojis in strings to learn more about this feature.

Disk space

If you need to save disk space (e.g. because you deploy to some service with tight size constraints), run this command (e.g. as an automated script after composer install) to compress the internal Symfony Intl data files using the PHP zlib extension:

1
2
# adjust the path to the 'compress' binary based on your application installation
$ php ./vendor/symfony/intl/Resources/bin/compress