date_i18n( string $dateformatstring, int|bool $timestamp_with_offset = false, bool $gmt = false )

Retrieve the date in localized format, based on a sum of Unix timestamp and timezone offset in seconds.

Contents

Description Description

If the locale specifies the locale month and weekday, then the locale will take over the format for the date. If it isn’t, then the date format string will be used instead.

Parameters Parameters

$dateformatstring

(string) (Required) Format to display the date.

$timestamp_with_offset

(int|bool) (Optional) A sum of Unix timestamp and timezone offset in seconds.

Default value: false

$gmt

(bool) (Optional) Whether to use GMT timezone. Only applies if timestamp is not provided.

Default value: false

Top ↑

Return Return

(string) The date, translated if locale specifies it.

Top ↑

Source Source

File: wp-includes/functions.php

96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
function date_i18n( $dateformatstring, $timestamp_with_offset = false, $gmt = false ) {
    global $wp_locale;
    $i = $timestamp_with_offset;
 
    if ( false === $i ) {
        $i = current_time( 'timestamp', $gmt );
    }
 
    /*
     * Store original value for language with untypical grammars.
     * See https://core.trac.wordpress.org/ticket/9396
     */
    $req_format = $dateformatstring;
 
    $dateformatstring = preg_replace( '/(?<!\\\\)c/', DATE_W3C, $dateformatstring );
    $dateformatstring = preg_replace( '/(?<!\\\\)r/', DATE_RFC2822, $dateformatstring );
 
    if ( ( ! empty( $wp_locale->month ) ) && ( ! empty( $wp_locale->weekday ) ) ) {
        $datemonth            = $wp_locale->get_month( date( 'm', $i ) );
        $datemonth_abbrev     = $wp_locale->get_month_abbrev( $datemonth );
        $dateweekday          = $wp_locale->get_weekday( date( 'w', $i ) );
        $dateweekday_abbrev   = $wp_locale->get_weekday_abbrev( $dateweekday );
        $datemeridiem         = $wp_locale->get_meridiem( date( 'a', $i ) );
        $datemeridiem_capital = $wp_locale->get_meridiem( date( 'A', $i ) );
        $dateformatstring     = ' ' . $dateformatstring;
        $dateformatstring     = preg_replace( '/([^\\\])D/', "\\1" . backslashit( $dateweekday_abbrev ), $dateformatstring );
        $dateformatstring     = preg_replace( '/([^\\\])F/', "\\1" . backslashit( $datemonth ), $dateformatstring );
        $dateformatstring     = preg_replace( '/([^\\\])l/', "\\1" . backslashit( $dateweekday ), $dateformatstring );
        $dateformatstring     = preg_replace( '/([^\\\])M/', "\\1" . backslashit( $datemonth_abbrev ), $dateformatstring );
        $dateformatstring     = preg_replace( '/([^\\\])a/', "\\1" . backslashit( $datemeridiem ), $dateformatstring );
        $dateformatstring     = preg_replace( '/([^\\\])A/', "\\1" . backslashit( $datemeridiem_capital ), $dateformatstring );
 
        $dateformatstring = substr( $dateformatstring, 1, strlen( $dateformatstring ) - 1 );
    }
    $timezone_formats    = array( 'P', 'I', 'O', 'T', 'Z', 'e' );
    $timezone_formats_re = implode( '|', $timezone_formats );
    if ( preg_match( "/$timezone_formats_re/", $dateformatstring ) ) {
        $timezone_string = get_option( 'timezone_string' );
        if ( false === $timestamp_with_offset && $gmt ) {
            $timezone_string = 'UTC';
        }
        if ( $timezone_string ) {
            $timezone_object = timezone_open( $timezone_string );
            $date_object     = date_create( null, $timezone_object );
            foreach ( $timezone_formats as $timezone_format ) {
                if ( false !== strpos( $dateformatstring, $timezone_format ) ) {
                    $formatted        = date_format( $date_object, $timezone_format );
                    $dateformatstring = ' ' . $dateformatstring;
                    $dateformatstring = preg_replace( "/([^\\\])$timezone_format/", "\\1" . backslashit( $formatted ), $dateformatstring );
                    $dateformatstring = substr( $dateformatstring, 1, strlen( $dateformatstring ) - 1 );
                }
            }
        } else {
            $offset = get_option( 'gmt_offset' );
            foreach ( $timezone_formats as $timezone_format ) {
                if ( 'I' === $timezone_format ) {
                    continue;
                }
 
                if ( false !== strpos( $dateformatstring, $timezone_format ) ) {
                    if ( 'Z' === $timezone_format ) {
                        $formatted = (string) ( $offset * HOUR_IN_SECONDS );
                    } else {
                        $prefix    = '';
                        $hours     = (int) $offset;
                        $separator = '';
                        $minutes   = abs( ( $offset - $hours ) * 60 );
 
                        if ( 'T' === $timezone_format ) {
                            $prefix = 'GMT';
                        } elseif ( 'e' === $timezone_format || 'P' === $timezone_format ) {
                            $separator = ':';
                        }
 
                        $formatted = sprintf( '%s%+03d%s%02d', $prefix, $hours, $separator, $minutes );
                    }
 
                    $dateformatstring = ' ' . $dateformatstring;
                    $dateformatstring = preg_replace( "/([^\\\])$timezone_format/", "\\1" . backslashit( $formatted ), $dateformatstring );
                    $dateformatstring = substr( $dateformatstring, 1 );
                }
            }
        }
    }
    $j = @date( $dateformatstring, $i );
 
    /**
     * Filters the date formatted based on the locale.
     *
     * @since 2.8.0
     *
     * @param string $j          Formatted date string.
     * @param string $req_format Format to display the date.
     * @param int    $i          A sum of Unix timestamp and timezone offset in seconds.
     * @param bool   $gmt        Whether to use GMT timezone. Only applies if timestamp was
     *                           not provided. Default false.
     */
    $j = apply_filters( 'date_i18n', $j, $req_format, $i, $gmt );
    return $j;
}

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
0.71 Introduced.

Top ↑

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/formatting.php: backslashit()

Adds backslashes before letters and before a number at the start of a string.
wp-includes/functions.php: date_i18n

Filters the date formatted based on the locale.
wp-includes/functions.php: current_time()

Retrieve the current time based on specified type.
wp-includes/class-wp-locale.php: WP_Locale::get_month()

Retrieve the full translated month by month number.
wp-includes/class-wp-locale.php: WP_Locale::get_month_abbrev()

Retrieve translated version of month abbreviation string.
wp-includes/class-wp-locale.php: WP_Locale::get_meridiem()

Retrieve translated version of meridiem string.
wp-includes/class-wp-locale.php: WP_Locale::get_weekday()

Retrieve the full translated weekday word.
wp-includes/class-wp-locale.php: WP_Locale::get_weekday_abbrev()

Retrieve the translated weekday abbreviation.
wp-includes/plugin.php: apply_filters()

Call the functions added to a filter hook.
wp-includes/option.php: get_option()

Retrieves an option value based on an option name.
Show 5 more uses Hide more uses

Top ↑

Used By Used By

Used By
Used By Description
wp-includes/blocks/latest-comments.php: render_block_core_latest_comments()

Renders the core/latest-comments block on server.
wp-admin/includes/misc.php: WP_Privacy_Policy_Content::privacy_policy_guide()

Output the privacy policy guide together with content from the theme and plugins.
wp-admin/includes/file.php: wp_privacy_send_personal_data_export_email()

Send an email to the user with a link to the personal data export file
wp-admin/includes/user.php: WP_Privacy_Requests_Table::get_timestamp_as_date()

Convert timestamp for display.
wp-admin/includes/class-wp-community-events.php: WP_Community_Events::format_event_data_time()

Adds formatted date and time items for each event in an API response.
wp-admin/includes/misc.php: heartbeat_autosave()

Autosave with heartbeat
wp-admin/includes/dashboard.php: wp_dashboard_recent_posts()

Generates Publishing Soon and Recently Published sections.
wp-admin/includes/ajax-actions.php: wp_ajax_date_format()

Ajax handler for date formatting.
wp-admin/includes/ajax-actions.php: wp_ajax_time_format()

Ajax handler for time formatting.
wp-admin/includes/ajax-actions.php: wp_ajax_wp_fullscreen_save_post()

Ajax handler for saving posts from the fullscreen editor.
wp-admin/includes/revision.php: wp_prepare_revisions_for_js()

Prepare revisions for JavaScript.
wp-admin/includes/meta-boxes.php: post_submit_meta_box()

Displays post submit form fields.
wp-admin/includes/meta-boxes.php: attachment_submit_meta_box()

Display attachment submit form fields.
wp-includes/general-template.php: wp_get_archives()

Display archive links based on type and format.
wp-includes/functions.php: mysql2date()

Convert given date string into a different format.
wp-includes/widgets.php: wp_widget_rss_output()

Display the RSS entries in a list.
wp-includes/post-template.php: wp_post_revision_title()

Retrieve formatted date timestamp of a revision (linked to that revisions’s page).
wp-includes/post-template.php: wp_post_revision_title_expanded()

Retrieve formatted date timestamp of a revision (linked to that revisions’s page).
Show 13 more used by Hide more used by

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 7You must log in to vote on the helpfulness of this note
    Contributed by Samuel Wood (Otto) —

    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. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
    Contributed by Andrey "Rarst" Savchenko —

    It is important to note that date_i18n():

    1. does not have full feature parity with date(), not all formats are supported (such as shorthands);
    2. does not accept Unix timestamp (despite documented to), the expected value is “WordPress timestamp” (offset by time zone);
    3. has issues with certain timezone settings, such as numerical ones;
    4. does nothing with $gmt argument under normal circumstances;

    Any use of this function must be carefully audited for correctness, especially in regards to output of time zones.

  4. Skip to note 4 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Dave Liske —

    To get both the date and time within a single string, use date_i18n twice with a separator. At the same time, you can also retrieve the local Date and Time formats that are set within the General Settings page.

    For example, to return: ‘March 3, 2018 @ 7:18 am’ (formatted for the US, Eastern Standard Time in the General Settings page):

    1
    $datetime = date_i18n(get_option('date_format'), current_time('timestamp')) .' @ '. date_i18n(get_option('time_format'), current_time('timestamp'));
  5. Skip to note 5 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by vee —
    1
    2
    3
    4
    $dt_gmt = '2018-12-03 00:00:00';
     
    echo 'date_i18n GMT, gmt=false: ' . date_i18n($settings_datetime_format, strtotime($dt_gmt)) . '<br>';
    echo 'date_i18n GMT, gmt=true: ' . date_i18n($settings_datetime_format, strtotime($dt_gmt), true) . '<br>';

    Result:

    date_i18n GMT, gmt=false: December 3, 2018 12:00 am
    date_i18n GMT, gmt=true: December 3, 2018 12:00 am

    The third argument has no effect if second argument was set.

    To display translated date/time based on WP settings (time zone, format). The $unixtimestamp argument must be convert from GMT like this.

    1
    2
    3
    $dt_gmt = '2018-12-03 00:00:00';
    $dt = get_date_from_gmt($dt_gmt, 'Y-m-d H:i:s');// convert from GMT to local date/time based on WordPress time zone setting.
    echo date_i18n(get_option('date_format') . ' ' . get_option('time_format') . ' (P)', strtotime($dt));// get format from WordPress settings.

    The result will be:

    ธันวาคม 3, 2018 7:00 am (+07:00)

    This is based on Thai language, Bangkok time zone.

    More examples are on [moderated]

You must log in before being able to contribute a note or feedback.