date_i18n() │ WP 0.71

Gets the localized date (translated to the current language) from the given unix timestamp.

If the output date uses a format with a month or week as a string, the function will attempt to translate them to the current language. In other cases, it is analogous to date() in PHP.

This function is a wrapper for the PHP function date(), which localizes the result.

It is recommended to use the newer function wp_date() instead of this function.

i18n is a shortened word for I{nternationalizatio}n (18 letters between the first and last letter).

Hooks from the function

date_i18n

Returns

String. Localized date.

Usage

date_i18n( $format, $timestamp_with_offset, $gmt );

$format(string) (required)

The format in which to output the date, example: F j, Y - November 6, 2010. Full list of formats.

$timestamp_with_offset(number)

Unix timestamp. By default, the current timestamp time() is used (if $gmt=true) or current_time('timestamp') (if $gmt=false).
Default: false

$gmt(boolean)

Whether to use the GMT zone.

true - set the timezone equal to Greenwich Mean Time (‎UTC+0).
false - set the timezone according to the site settings.

Works only if $unixtimestamp is not specified, which makes sense because if we specify a timestamp, the script cannot guess what timezone it is and how much it needs to be shifted to get the desired result. $gmt is needed when the timestamp is not specified (set to false) and the current time is taken...

Default: false

Examples

#1 Localization of the php function date() in WordPress

Demonstration of the function:

// current time

echo date_i18n( 'j F Y H:i:s', false ); 
// 12 Aug 2018 02:08:59

echo date_i18n( 'j F Y H:i:s', false, true ); 
// August 11, 2018 21:08:59 - GMT works because no time is specified

// specific time

echo date_i18n( 'j M Y H:i:s', strtotime('1999-11-15' ) ); 
// Nov 15, 1999 00:11:00

echo date_i18n( 'j M Y H:i:s', strtotime('1999-11-15' ), 1 ); 
// Nov 15, 1999 00:11:00 - GMT does not work because the time tag is specified

#2 The functions notes

The date_i18n() function basically behaves exactly like the normal PHP date() function, except that it also translates things like month names and weekdays and similar into the current locale for the site. You can replace a call to date() with a call to date_i18n(), using the same arguments that date() normally takes.

The date_i18n() function also takes an additional argument, which should be used only if you’re specifying GMT (UTC) time and not a local time.

The core of WordPress includes the necessary pieces to translate months and days and so forth in the core code, so this function is one translation function which does not need a text-domain when used in plugins and themes. The translations will always be included in the core language packs.

Note that the “format”, however, is not converted to a local one if you manually specify it. If you need a localized format, then you should use get_option('date_format') if you need the format set by the user in Settings > General, and thus one of their choosing. Alternatively, you can wrap your predefined format in __() in order to allow translators to adjust the date to the proper local format. If you do so, then you should also include a translator comment, to let the translators know what the date format is referring to and where it is used, so they can convert it accurately.

#3 Use the genitive case

If you need to use the genitive case of a month in Greek you can use (WHILE formatted for GREEK in General Settings page):

$genitive_date = date_i18n( 'l',  strtotime( '29-11-2018' ) ) . ', ' . date_i18n( 'j F Y', strtotime( '29-11-2018' ) );

The above returns: Πέμπτη, 29 Νοεμβρίου 2018 Instead of:

$date = date_i18n( 'l, j F Y', strtotime( '29-11-2018' ) );

Which returns: Πέμπτη, 29 Νοέμβριος 2018

#4 Get both date and time within a single string

To do it just concatenate the two options:

$format = get_option('date_format') .' @ '. get_option('time_format');

$datetime = date_i18n( $format );

var_dump( $datetime ); // March 3, 2018 @ 7:18 am

#5 Convert another UTC time to your own timezone.

Let us suppose you are in UTC+10 timezone And want to convert another timezone to your timezone.

$timestamp_with_offset = strtotime( '2020-05-06 23:42:59' ) + get_option( 'gmt_offset', 0 ) * HOUR_IN_SECONDS;

$converted_date = date_i18n( get_option( 'date_format' ), $timestamp_with_offset );

#6 Way to show your install date/time

A simple way to show the default format of your install date/time; and to see if it works well with i18n formatting is to pull both date and time using PHP:

$format = get_option('date_format') . ' ' . get_option('time_format');
$check_stamp = date_i18n( $format ); // February 25, 2022 11:36 pm

If it shows incorrectly then you can go to your Setting > General to make good.

Changelog

Since 0.71	Introduced.
Since 5.3.0	Converted into a wrapper for wp_date().

`date_i18n() date i18n` code ^{WP 6.8.3}

wp-includes/functions.php

function date_i18n( $format, $timestamp_with_offset = false, $gmt = false ) {
	$timestamp = $timestamp_with_offset;

	// If timestamp is omitted it should be current time (summed with offset, unless `$gmt` is true).
	if ( ! is_numeric( $timestamp ) ) {
		// phpcs:ignore WordPress.DateTime.CurrentTimeTimestamp.Requested
		$timestamp = current_time( 'timestamp', $gmt );
	}

	/*
	 * This is a legacy implementation quirk that the returned timestamp is also with offset.
	 * Ideally this function should never be used to produce a timestamp.
	 */
	if ( 'U' === $format ) {
		$date = $timestamp;
	} elseif ( $gmt && false === $timestamp_with_offset ) { // Current time in UTC.
		$date = wp_date( $format, null, new DateTimeZone( 'UTC' ) );
	} elseif ( false === $timestamp_with_offset ) { // Current time in site's timezone.
		$date = wp_date( $format );
	} else {
		/*
		 * Timestamp with offset is typically produced by a UTC `strtotime()` call on an input without timezone.
		 * This is the best attempt to reverse that operation into a local time to use.
		 */
		$local_time = gmdate( 'Y-m-d H:i:s', $timestamp );
		$timezone   = wp_timezone();
		$datetime   = date_create( $local_time, $timezone );
		$date       = wp_date( $format, $datetime->getTimestamp(), $timezone );
	}

	/**
	 * Filters the date formatted based on the locale.
	 *
	 * @since 2.8.0
	 *
	 * @param string $date      Formatted date string.
	 * @param string $format    Format to display the date.
	 * @param int    $timestamp A sum of Unix timestamp and timezone offset in seconds.
	 *                          Might be without offset if input omitted timestamp but requested GMT.
	 * @param bool   $gmt       Whether to use GMT timezone. Only applies if timestamp was not provided.
	 *                          Default false.
	 */
	$date = apply_filters( 'date_i18n', $date, $format, $timestamp, $gmt );

	return $date;
}