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.

Source Code

Related Links

• http://cldr.unicode.org/
• https://en.wikipedia.org/wiki/Languages_used_on_the_Internet
• https://en.wikipedia.org/wiki/List_of_countries_by_number_of_Internet_users
• http://php.net/manual/en/function.date.php
• https://github.com/unicode-cldr/cldr-dates-modern/
• https://github.com/unicode-cldr/cldr-numbers-modern/
• https://github.com/unicode-cldr/cldr-localenames-modern/

Example Code

// FastSitePHP provides an easy to use Localization (l10n) API to allow date
// and number formatting with a user’s local language and regional settings.

// Create a new Lang L10N Object
$l10n = new \FastSitePHP\Lang\L10N();

// Settings can optionally be passed when the class is first created.
/*
$locale = 'en-US';
$timezone = 'America/Los_Angeles';
$l10n = new \FastSitePHP\Lang\L10N($locale, $timezone);
*/

// Use the [timezone()] function to get or set the timezone that will be used
// when formatting dates and times.
//
// If you have a site or application that has users in multiple timezones or
// countries an application design that works well is to save all dates and
// times in UTC and then format based on the users selected timezone.
//
// This example prints:
/*
    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) {
    // Change the Timezone
    $l10n->timezone($timezone);
    // Print the formated date and time
    echo $l10n->timezone();
    echo ' = ';
    echo $l10n->formatDateTime($date_time);
    echo '<br>';
}
echo '<br>';

// Change the Timezone back to UTC for the next examples
$l10n->timezone('UTC');

// The [$date_time] parameter for the functions [formatDateTime(), formatDate(),
// and formatTime()] is either a Unix Timestamp (int) or a string in format
// of 'YYYY-MM-DD HH:MM:SS' or 'YYYY-MM-DD'
$date_time = 1896181200;
$date_time = '2030-02-01 13:00:00';

// Print Date Time with different locales using [locale()] and
// [formatDateTime()] functions. This example prints:
/*
    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) {
    // Change the Locale
    $l10n->locale($locale);
    // Print the formated date and time
    echo $l10n->locale();
    echo ' = ';
    echo $l10n->formatDateTime($date_time);
    echo '<br>';
}
echo '<br>';

// In addition to [formatDateTime()] functions [formatDate()] and
// [formatTime()] can be used to show only a date or time. Prints:
/*
    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>';

// Print a formatted Number with different locales using [locale()] and
// [formatNumber()] functions. Decimal places are optional and default
// to 0. This example prints:
/*
    en-US =  1,234,567,890.12345
    en-IN = 1,23,45,67,890.12345
    fr    =  1 234 567 890,12345
    fa    =  ۱٬۲۳۴٬۵۶۷٬۸۹۰٫۱۲۳۴۵
*/
$number = 1234567890.12345;
$decimals = 5;
$locales = ['en-US', 'en-IN', 'fr', 'fa'];
foreach ($locales as $locale) {
    // [locale()] is a chainable getter and setter function
    // so it can be set and read from the same line.
    echo $l10n->locale($locale)->locale();
    echo ' = ';
    echo $l10n->formatNumber($number, $decimals);
    echo '<br>';
}

// Get supported Locales, Languages, and Timezones
$locales    = $l10n->supportedLocales();
$langugages = $l10n->supportedLanguages();
$timezones  = $l10n->supportedTimezones();

Methods

__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');

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.

Returns: array

supportedLanguages()

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

Returns: array

locale($locale = null)

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');

Returns: $this | null | string

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()].

Returns: array

timezone($timezone = null)

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'

Returns: $this | null | string

• http://php.net/manual/en/timezones.php

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.

Returns: 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()].

Returns: 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()].

Returns: 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'    :  ١٬٢٣٤٬٥٦٧٬٨٩٠٫١٢٣٤٥

Returns: string