Categories
PHP

Localizing Dates with IntlDateFormatter Class

How to use the IntlDateFormatter class to handle tasks as internationalized dates, calendar generation, time and date formatting, etc.

This class allows you to display dates in a localized format using pattern strings and/or canned patterns. This class represents the ICU date formatting functionality (formatting of dates in milliseconds). See examples: Localizing dates in foreign languages.

https://php.net/manual/class.intldateformatter.php

Syntax: Creating a new instance of IntlDateFormatter object:

<?php
 $formatter = new IntlDateFormatter(
   ?string $locale,
   int $dateType = IntlDateFormatter::FULL,
   int $timeType = IntlDateFormatter::FULL,
   IntlTimeZone|DateTimeZone|string|null $timezone = null,
   IntlCalendar|int|null $calendar = null,
   ?string $pattern = null
 );

OR using IntlDateFormatter::create() static method syntax:

<?php
 $formatter = IntlDateFormatter::create(
   ?string $locale,
   int $dateType = IntlDateFormatter::FULL,
   int $timeType = IntlDateFormatter::FULL,
   IntlTimeZone|DateTimeZone|string|null $timezone = null,
   IntlCalendar|int|null $calendar = null,
   ?string $pattern = null
 ); 

Or using the procedural style with datefmt_create() function:

<?php
 $formatter = datefmt_create(
   ?string $locale,
   int $dateType = IntlDateFormatter::FULL,
   int $timeType = IntlDateFormatter::FULL,
   IntlTimeZone|DateTimeZone|string|null $timezone = null,
   IntlCalendar|int|null $calendar = null,
   ?string $pattern = null
 ); 
  1. $locale: Locale in which the date would be formatted (locale name, e.g. en_US). If null, it will use the default locale (Locale::getDefault())
  2. $dateType: Date type to use:
    • IntlDateFormatter::NONE default value
      The default value and its mean do not include the date.
    • IntlDateFormatter::FULL
      Tuesday, January 31, 2023 (Completely specified style)
    • IntlDateFormatter::LONG
      January 31, 2023 (long style)
    • IntlDateFormatter::MEDIUM
      Jan 31, 2023 (medium style)
    • IntlDateFormatter::SHORT
      1/31/23 (abbreviated style)
  3. $timeType: Time type (same as $dateType)
    • IntlDateFormatter::NONE default value
      The default value and its mean do not include the time.
    • IntlDateFormatter::FULL
      1:35:51 PM Pacific Standard Time (Completely specified style)
    • IntlDateFormatter::LONG
      1:35:51 PM PST (long style)
    • IntlDateFormatter::MEDIUM
      1:35:51 PM (medium style)
    • IntlDateFormatter::SHORT
      1:35 PM (abbreviated style)
  4. $timezone: Time zone ID, default is date_default_timezone_get().
  5. $calendar: The following constants are used:
    • IntlDateFormatter::TRADITIONAL
      A Non-Gregorian Calendar must be specified in the locale, for example $locale = 'hi@calendar=BUDDHIST'. See Islamic Calendar, and Hebrew Calendar examples.
    • IntlDateFormatter::GREGORIAN (Gregorian Calendar. It is the default calendar)
  6. $pattern (optional):
    Formatting patterns, see https://unicode-org.github.io/icu/userguide/format_parse/datetime/

Localizing dates in foreign languages:

Example: Using Danish Locale (procedural style):

<?php
 $fmt = datefmt_create(
          'da_DK',
          IntlDateFormatter::FULL,
          IntlDateFormatter::FULL,
          'America/Los_Angeles',
          IntlDateFormatter::GREGORIAN
       );
 echo datefmt_format( $fmt , time());

The preceding code outputs:

onsdag den 1. februar 2023 kl. 12.56.57 Pacific-normaltid

Example: Displaying Dates in Urdu (OOP Style):

The following code will automatically translate the current date and time into the Urdu language:

<?php
 $fmt = new IntlDateFormatter(
          'ur_PK',
          IntlDateFormatter::FULL,
          IntlDateFormatter::FULL,
          'America/Los_Angeles',
          IntlDateFormatter::GREGORIAN
       );
 echo $fmt->format(time());
 //بدھ، 1 فروری، 2023 1:07:12 PM پیسفک اسٹینڈرڈ ٹائم

Example: Translate the Date and Time into Arabic

<?php
 $fmt = new IntlDateFormatter(
          'ar_SA',
          IntlDateFormatter::FULL,
          IntlDateFormatter::FULL,
          'America/Los_Angeles',
          IntlDateFormatter::GREGORIAN
       );
 echo $fmt->format( time() );
 //الأربعاء، ١ فبراير ٢٠٢٣ م في ١:١٠:٥٢ م توقيت المحيط الهادي الرسمي

The Islamic Calendar

The following code prints the current Islamic (Hijri) date in en_US (English) locale:

Example: Displaying Current Hijri Date using the IntlDateFormatter::TRADITIONAL.

<?php
 $fmt = new IntlDateFormatter(
          'en_US@calendar=ISLAMIC',
          IntlDateFormatter::FULL,
          IntlDateFormatter::FULL,
          'America/Los_Angeles',
          IntlDateFormatter::TRADITIONAL
       );
 echo $fmt->format(time());
 //Wednesday, Rajab 11, 1444 AH at 1:22:34 PM Pacific Standard Time

The following code prints the current Islamic (Hijri) date in ar_SA (Arabic) locale:

<?php
 $fmt = new IntlDateFormatter(
          'ar_SA@calendar=ISLAMIC',
          IntlDateFormatter::FULL,
          IntlDateFormatter::FULL,
          'America/Los_Angeles',
          IntlDateFormatter::TRADITIONAL
       );
 echo $fmt->format(time());
 //الأربعاء، ١١ رجب ١٤٤٤ هـ في ١:٢٤:٠٢ م توقيت المحيط الهادي الرسمي

The Jewish Calendar

The following code prints the current Hebrew date in en_US (English) locale:

<?php
 $fmt = new IntlDateFormatter(
          'en_US@calendar=Hebrew',
          IntlDateFormatter::FULL,
          IntlDateFormatter::FULL,
          'America/Los_Angeles',
          IntlDateFormatter::TRADITIONAL
       );
 echo $fmt->format(time());
 //Wednesday, 10 Shevat 5783 at 1:42:32 PM Pacific Standard Time

The following code prints the current Jewish date in he_IL (Hebrew) locale:

<?php
 $fmt = new IntlDateFormatter(
          'he_IL@calendar=Hebrew',
          IntlDateFormatter::FULL,
          IntlDateFormatter::FULL,
          'America/Los_Angeles',
          IntlDateFormatter::TRADITIONAL
       );
 echo $fmt->format(time());
 //יום רביעי, י׳ בשבט תשפ״ג בשעה 13:46:36 שעון מערב ארה״ב (חורף)

The Date and Time Tutorials: