FastSitePHP\Lang\L10N

Localization (l10n) API

Contains functions for formatting dates, times, and numbers.

[l10n] is spelled "Localisation" in British English. [l10n] is an acronym/numeronym that represents ("l" + 10 characters + "n"). The difference is US English uses "z" while British English uses an "s" in the spelling of the word.

Código Fonte

GitHub

Código de Exemplo

Formatando Datas, Horas e Números

// O FastSitePHP provê uma API de Localização (l10n) de fácil utilização
// para permitir formatação de datas e números com a linguagem local do
// usuário e configurações regionais.

// Cria um novo Objeto Lang L10N
$l10n = new \FastSitePHP\Lang\L10N();

// Definições são passadas de forma opcional quando a classe é criada
/*
$locale = 'pt-BR';
$timezone = 'America/Sao_Paulo';
$l10n = new \FastSitePHP\Lang\L10N($locale, $timezone);
*/

// Utiliza a função [timezone()] para obter ou definir o fuso horário que
// será utilizado ao formatar datas e horários.
//
// Se você tem um site ou aplicação que tenha usuários em múltiplos fusos
// horários our países, um design de aplicação que funciona bem é salvar
// todas as datas e horários em UTC e daí formatá-los baseando-se no fuso
// horário escolhido pelo usuário.
//
// Este exemplo imprime:
/*
    UTC                 = 2030-01-01 00:00
    Asia/Tokyo          = 2030-01-01 09:00
    America/Los_Angeles = 2029-12-31 16:00
*/
$date_time = '2030-01-01 00:00:00';
$timezones = ['UTC', 'Asia/Tokyo', 'America/Los_Angeles'];
foreach ($timezones as $timezone) {
    // Mude o Fuso Horário
    $l10n->timezone($timezone);
    // Imprime a data e horário formatados
    echo $l10n->timezone();
    echo ' = ';
    echo $l10n->formatDateTime($date_time);
    echo '<br>';
}
echo '<br>';

// Mude o Fuso Horário de volta para UTC para os próximos exemplos
$l10n->timezone('UTC');

// O parâmetro [$date_time] para as funções [formatDateTime(), formatDate()
// e formatTime()] é um carimbo de data/hora Unix (int) ou uma string no
// formato de 'YYYY-MM-DD HH:MM:SS' ou 'YYYY-MM-DD'
$date_time = 1896181200;
$date_time = '2030-02-01 13:00:00';

// Imprima Data e Hora com localizações diferentes utilizando as funções
// [locale()] e [formatDateTime()]. Este exemplo imprime:
/*
    ko    = 2030. 2. 1. 오후 1:00
    bn    = ১/২/২০৩০ ১:০০ PM
    en-US = 2/1/2030, 1:00 PM
    de-CH = 01.02.2030, 13:00
    ar    = ‏١‏/٢‏/٢٠٣٠ ١:٠٠ م
*/
$locales = ['ko-KR', 'bn-BD', 'en-US', 'de-CH', 'ar'];
foreach ($locales as $locale) {
    // Mude a Localização
    $l10n->locale($locale);
    // Imprima a data e hora formatados
    echo $l10n->locale();
    echo ' = ';
    echo $l10n->formatDateTime($date_time);
    echo '<br>';
}
echo '<br>';

// Além de [formatDateTime()] as funções [formatDate()] e [formatTime()]
// podem ser utilizadas para mostrar somente uma data ou hora. Imprime:
/*
    01/02/2030
    13:00:00
*/
$l10n->locale('fr-FR');
echo $l10n->formatDate($date_time);
echo '<br>';
echo $l10n->formatTime($date_time);
echo '<br>';
echo '<br>';

// Imprima um Número formatado com diferentes localizações utilizando as
// funções [locale()] e [formatNumber()]. Posições decimais são opcionais
// e seu padrão é 0. Este exemplo imprime:
/*
    en-US =  1,234,567,890.12345
    en-IN = 1,23,45,67,890.12345
    fr    =  1 234 567 890,12345
    fa    =  ۱٬۲۳۴٬۵۶۷٬۸۹۰٫۱۲۳۴۵
*/
$numero = 1234567890.12345;
$decimals = 5;
$locales = ['en-US', 'en-IN', 'fr', 'fa'];
foreach ($locales as $locale) {
    // [locale()] é uma função getter e setter encadeável assim ela pode ser
    // definida e lida de uma mesma linha.
    echo $l10n->locale($locale)->locale();
    echo ' = ';
    echo $l10n->formatNumber($numero, $decimals);
    echo '<br>';
}

// Obtenha Localizações, Idiomas e Fusos Horários suportados
$locales    = $l10n->supportedLocales();
$languages = $l10n->supportedLanguages();
$timezones  = $l10n->supportedTimezones();

Métodos

__construct($locale = null, $timezone = null)

Class Constructor Settings can optionally be set when the class is first created.

Example:
  $l10n = new \FastSitePHP\Lang\L10N('en-US', 'America/Los_Angeles');

function supportedLocales()

Return a list of supported locales. Each locale has a JSON file in the [Locales] sub-folder.

Territories (Countries) are not always included when the language has a primary Country. For example French ‘fr’ and German ‘de’ do not have locales for ‘fr-FR’ and ‘de-DE’ however setting [locale()] with either value will match to the correct language.

Retorna: array

function supportedLanguages()

Return an associative array of Supported Languages. The key will contain the language abbreviation and the value will contain the language in English.

Retorna: array

locale($locale = null)

Propriedade Getter / Setter

Get or set the locale to be used when formatting dates, times, and numbers. When setting the locale this function is chainable and returns the L10N object instance.

Examples:
  Get:
    $current_locale = $l10n->locale();
  Set:
    $l10n->locale('zh');
    $l10n->locale('fr-FR');
    $l10n->locale('en-US');

Retorna: $this | null | string

function supportedTimezones()

Return an array of timezones that can be set from the function [timezone()]. This function simply returns the results of the native PHP function [\DateTimeZone::listIdentifiers()].

Retorna: array

timezone($timezone = null)

Propriedade Getter / Setter

Get or set the timezone to be used when formatting dates and times. When setting the timezone this function is chainable and returns this L10N object instance.

Examples:
  $time = '2030-01-01 00:00:00';
  $l10n->timezone($timezone)->formatDateTime($time);

  time = $timezone:
  '2030-01-01 00:00' = 'UTC'
  '2030-01-01 09:00' = 'Asia/Tokyo'
  '2029-12-31 16:00' = 'America/Los_Angeles'

Retorna: $this | null | string

formatDateTime($date_time)

Format a date and time string based on the selected locale. Seconds are not included in the result.

Example:
  $l10n->timezone('UTC')->formatDateTime('2030-02-01 13:00:30');

Returns:
  'ko-KR' : 2030. 2. 1. 오후 1:00
  'bn-BD' : ১/২/২০৩০ ১:০০ PM
  'en-US' : 2/1/2030, 1:00 PM
  'de-CH' : 01.02.2030, 13:00

To return formatted current date and time:
  $l10n->formatDateTime(time());

If an invalid time is passed and timezone is set then this function will return [null]; otherwise if timezone is not set then the initial value for Unix Timestamp (00:00:00 on 1 January 1970) will be returned.

When using Language 'fa' (Farsi/Persian) or locale 'ar-SA' (Arabic - Saudi Arabia) dates are currently returned with Latin Digits using the Gregorian Calendar instead of Jalaali Calendar for 'fa' and Hijri Calendar for 'ar-SA'. If you need either of these calendars on a web page an option is to use the browser built-in object [Intl.DateTimeFormat] from JavaScript.

Retorna: string | null

formatDate($date)

Format a date string (excluding time) based on the selected locale.

Example:
  $l10n->timezone('UTC')->formatDate('2030-02-01 13:00:30');

Returns:
  'ko-KR' : 2030. 2. 1.
  'bn-BD' : ১/২/২০৩০
  'en-US' : 2/1/2030
  'de-CH' : 01.02.2030

To return formatted current date:
  $l10n->formatDate(time());

See additional notes in [formatDateTime()].

Retorna: string | null

formatTime($time)

Format a time string (excluding date) based on the selected locale. Hours, minutes, and seconds are included in the result.

Example:
  $l10n->timezone('UTC')->formatTime('2030-02-01 13:00:30');

Returns:
  'ko-KR' : 오후 1:00:30
  'bn-BD' : ১:০০:৩০ PM
  'en-US' : 1:00:30 PM
  'de-CH' : 13:00:30

To return formatted current time:
  $l10n->formatTime(time());

See additional notes in [formatDateTime()].

Retorna: string | null

formatNumber($number, $decimals = 0)

Format a number based on the selected locale. Defaults to zero decimal places.

Example:
  $l10n->formatNumber(1234567890.12345, 5)

Returns:
  'en-US' :  1,234,567,890.12345
  'en-IN' : 1,23,45,67,890.12345
  'fr'    :  1 234 567 890,12345
  'ar'    :  ١٬٢٣٤٬٥٦٧٬٨٩٠٫١٢٣٤٥

Retorna: string