PHP Internationalization and Localization Localizing Dates and Times

PHP Internationalization and Localization

Localizing Dates and Times

Problem

You want to display dates and times in a locale-specific manner.

Solution

Use the date or time argument type, with an optional short, medium, long, or full style inside a MessageFormatter message:

       $when = 1376943432; // Seconds since epoch

       $message = "It is {0,time,short} on {0,date,medium}.";

       $fmt = new MessageFormatter('en_US', $message);

       print $fmt->format(array($when));

This prints:

       It is 4:17 PM on Aug 19, 2013.

Use a formatting pattern with a date or time argument type inside a MessageFormatter message:

       $when = 1376943432; // Seconds since epoch

       $message = "Maintenant: {0,date,eeee dd MMMM y}";

       $fmt = new MessageFormatter('fr_FR', $message);

       print $fmt->format(array($when));

This prints:

       Maintenant: lundi 19 août 2013

Use the format() method of an IntlDateFormatter:

       $when = 1376943432; // Seconds since epoch

       $fmt = new IntlDateFormatter('en_US', IntlDateFormatter::FULL,

                                                                 IntlDateFormatter::FULL);

       print $fmt->format($when);

This prints:

       Monday, August 19, 2013 at 8:17:12 PM GMT

Discussion

The date and time argument types for MessageFormatter make it easy to include appropriate localized representations of dates and times in your output. These “preset” formats not only respect the appropriate settings for a locale by including the right information in the right order (for example, distinguishing between places that list month number before day number and places that list day number before month number), but also translate words for months and days of the week into the appropriate language.

If you want more control over the date and time elements that appear in your message, supply a format pattern.

Table Date and time format pattern characters

____________________________________________________________________________________________________

______________________________________________________________________

PHP’s epoch timestamps and DateTime objects don’t support milliseconds, so the S, SS, and SSS characters are always zeros. Unless a special meaning is listed in the table for a repeating character, most other characters when repeated enable you to include one or more leading zeros. For example, because m represents minute, mm produces 08 for the eighth minute past the hour.

Although a date or time argument type in a MessageFormatter message expects an integer argument representing seconds since epoch, the IntlDateFormatter accomodates more ways to specify the time or date you care about. You can provide the value to format as a DateTime object or as an array of time parts as returned by local time(). For example:

       $fmt = new IntlDateFormatter('en_US', IntlDateFormatter::FULL,

                                                                 IntlDateFormatter::FULL,

                                                                 'America/Chicago');

       // Z for time zone means UTC

       $obj = new DateTime('2013-08-20T12:34:56Z');

       $parts = array('tm_sec' => 56,

                                   'tm_min' => 34,

                                   'tm_hour' => 12,

                                   'tm_mday' => 20,

                                   'tm_mon' => 7, /* 0 = January */

                                   'tm_year' => 113); /* 0 = 1900 */

       print $fmt->format($obj) . "\n";

       print $fmt->format($parts) . "\n";

This prints:

       Tuesday, August 20, 2013 at 7:34:56 AM Central Daylight Time

       Tuesday, August 20, 2013 at 12:34:56 PM Central Daylight Time

The values are formatted for output as appropriate for the en_US locale and the America/ Chicago time zone. This means that the hour specified in the DateTime object—12 P.M. GMT—is adjusted to 7 A.M. Central Daylight Time (the active time zone for August 20, 2013 in Chicago). The time parts provided in the second call to format() do not include a time zone, so they are assumed to be the same time zone as specified in the IntlDateFormatter constructor.

Starting in PHP 5.5, the IntlDateFormatter class also has a helper method to produce localized, formatted date/time strings in one step, rather than having to construct a new IntlDateFormatter and then call format(). The static IntlDateFormatter::fromObject() method takes three arguments: a DateTime object, a format, and a locale, and returns the formatted date/time string.

Example  DateTime object, format, and locale

       $obj = new DateTime('2013-08-20T12:34:56');

       print IntlDateFormatter::formatObject($obj, 'eeee dd MMMM y', 'es_ES') . "\n";

       print IntlDateFormatter::formatObject($obj, IntlDateFormatter::FULL, 'fr_FR') .

                                                                                                                                                  "\n";

       // First element is date format, second is time format

       $formats = array(IntlDateFormatter::FULL, IntlDateFormatter::SHORT);

       print IntlDateFormatter::formatObject($obj, $formats, 'de_DE') . "\n";

This prints:

       martes 20 agosto 2013

       mardi 20 août 2013 12:34:56 UTC

       Dienstag, 20. August 2013 12:34

As shown, the second argument to formatObject can either be an explicit format pattern string, one of the IntlDateFormatter formatting style constants, or an array of two formatting style constants. If a format pattern string is provided, that is used. If one formatting style constant is provided, that is used for both date and time. If an array of two formatting style constants is provided, the first is used for the date style and the second for the time style.