Module:DateI18n/doc

This module is rated as ready for general use. It has reached a mature form and is thought to be bug-free and ready for use wherever appropriate. To reduce server load and bad output, it should be improved by sandbox testing rather than repeated trial-and-error editing.

This module is subject to page protection. It is a highly visible module in use by a very large number of pages, or is substituted very frequently. Because vandalism or mistakes would affect many pages, and even trivial editing might cause substantial load on the servers, it is protected from editing.

Summary

This module is intended for creating of date strings in any language. It serves as a back-end of {{Date}} template. See documentation of that template for documentation.

The internationalization of the date formats can be found at Data:DateI18n.tab and Data:I18n/MonthCases.tab. Module:DateI18n is called from Module:ISOdate.

Using this module from templates

Date

This module should only be called from {{Date}} template. Please call that template to access this module. Also see {{Date}} template for full documentation

Usage:

{{#invoke:DateI18n|Date|year=...|month=...|day=...|hour=...|minute=...|second=...|tzhour=...|tzmin=...|lang=...}}

Parameters:

year, month, day, hour, minute, second

(most are optional) parameters specifying part of the date

tzhour, tzmin

(optional and rarely used) time zone offset from UTC

lang

(optional) language to be used to display the date. If not specified language of the user will be used

class

(optional) Allows setting of the HTML class of the time node where the date is included. This is useful for microformats. The default value is, for legacy reasons, "dtstart" (used by hCalendar). See the microformats project. "class=" will remove all metadata.

case

(optional) By default each language uses preferred form of the date, which typically has month in nominative or genitive grammatical case. With case parameter one can overwrite the preferred case with some other one used by a given language. Parser function {{#time}} stores nominative and genitive forms, others are stored in Data:I18n/MonthCases.tab. This functionality is mostly used by Module:Complex date.

trim_year

trim_year parameter

Example:

{{#invoke:DateI18n|Date|year=1990|month=Oct|day=01|lang=en}} produces 1 October 1990

Using this module from Lua code

In order to use the functions in this module from another Lua module you first have to import this module.

Example:

local DateMod = require('Module:DateI18n')

_Date

Usage:

date_string = DateMod._Date({year,month,day,hour,minute, second},lang)

I18n tables

This module stores all the language specific settings in two files in "Data" namespace: Data:DateI18n.tab and Data:I18n/MonthCases.tab

Data:DateI18n.tab

Translation table with different forms of dates. Outputs are in the format used by {{#time}} parser function. There are several date formats supported, which depend on the data provided

For marking litteral text (notably with Basic Latin letters) that must be ouput as is (and not recognized as possible placeholders for formatting individual date fields values), you may use straight ASCII single quotes within all specified formats (instead of the straight ASCII double quotes, normally required for litteral text in forms given to the {{#time:}} parser function).

If a specified format needs to embed an apostrophe to be returned litterally (and not to be recognized as the alternative delimiter now reserved for marking litterals for {{#time:}}), the curly apostrophe-quote character U 2019 (’) must be used instead, or any other apostrophe-like character suitable for the target language: the ASCII single quote is ambiguous in all languages (and can also cause problems with Mediawiki syntax for marking bold/italic styles surrounding the generated date) and there are other preferred characters.

Note that formats 'YMDHMS' and 'YMDHM' are legacy aliases present in Data:DateI18n.tab. They have two 'M' in them: the first 'M' means month, the second 'M' means minute only after the 'H' meaning hour. These aliases have been kept in the tabular data, for compatiblity with some other modules that would expect these two legacy keys. For adding more formats showing time with fields for hour, minute and second, distinctive lower case letters 'hms' should be used.

Date formats

Format string	Meaning	Comments
YMDhms or YMDHMS	"YYYY-MM-DD, hh:mm:ss" format for: year, month name, day of the month, hour, minute, and second	Most items in the list use format created from the YMD format, with hour, minutes and seconds added with ", HH:MM:SS". All languages using this format do not have to be listed, as they default to this simple rule used in English.
YMDhm or YMDHM	"YYYY-MM-DD, hh:mm" format for: year, month name, day of the month, hour, and minute	Most items in the list use format created from the YMD format, with hour and minutes added with ", HH:MM". All languages using this format do not have to be listed, as they default to to this simple rule used in English.
YMD	"YYYY-MM-DD" format for: year, month name, and day of the month	Languages using the same format as English do not need to be listed.
YM	"YYYY-MM" format for: year and month name	Most items in the list use the format created from the M format, with the year added with " YYYY" and created from the Y format. All languages using this format do not have to be listed, as they default to to this simple rule used in English.
Y	"YYYY" format for: the year only	Most languages show year as a simple number, those do not have to be listed as they will default to the same format as English.
MDhms	"MM-DD, hh:mm:ss" format for: month name, day of the month, hour, minute, and second	Most items in the list use the format created from the MD format, with hour, minutes and seconds added with ", HH:MM:SS". All languages using this format do not have to be listed, as they default to this simple rule used in English.
MDhm	"MM-DD, hh:mm" format for: month name, day of the month, hour, and minute	Most items in the list use the format created from the MD format, with hour, minutes and seconds added with ", HH:MM". All languages using this format do not have to be listed, as they default to this simple rule used in English.
MD	"MM-DD" format for: month name and day of the month	Most items in the list use the format created from the M format, with the day number prepended with "DD ". Some language prefer placing the day of the month after the month name. Some languages need to use a genitive form for the month name, or will use different forms for specific days of the month All languages using this format do not have to be listed, as they default to this simple rule used in English.
M	"MM" format for: the month name only	Languages may have multiple forms to be listed for specific months, depending on their grammatical case of use.

Special cases

Some languages like Catalan, Basque, French, or Irish use different forms for dates, depending on the day of the month.

The format of the Tabular Data (and its eiting interface) allowed only simple strings to be stored in multi-language arrays, not JSON subtables. So the following is still not accepted in Tabular data pages on this wiki, even though it is a valid JSON syntax:

[
    ...
    "en": "j' 'F' 'Y",
    ...
    "fr" : { "default": "j' 'F' 'Y", "d01": "j'<sup>er</sup> 'F' 'Y" },
    ...
]

In order to overcome that, we stored the JSON subtable inside translation strings (already surrounded by ASCII double quotes required by JSON for the main tabular data) by using curly quotes instead of ASCII quotes for strings in the embedded JSON table; that might look like:

[
    ...
    "en": "j' 'F' 'Y",
    ...
    "fr" : "{ ‟default”: ‟j' 'F' 'Y”, ‟d01”: ‟j'<sup>er</sup> 'F' 'Y” }",
    ...
]

This string is converted by replacing curly double quotes, any one in U 201C..U 201F (“”„‟), found in tabular data with regular ASCII straight double-quotes as:

{ "default": "j' 'F' 'Y", "d01": "j'<sup>er</sup> 'F' 'Y" }

which is then parsable as valid JSON and converted into a Lua dictionary table.

Using curly double quotes is supported only in string values embedding JSON data (i.e. a table delimited by braces "{}" inside the string) containing at least the field named ‟default”. For all other formats (using simple strings), you must use ASCII double quotes to delimit them, and curly double quotes will be recognized as part of the litteral text in the ouput.

Then the field value representing the day of the month of the given date is converted into a key by prepending ‟d” to the 2-digit integer for that day. If this key is found in the parsed dictionary, then the form specified by the value associated to that key will be used, otherwise we will use the form specified by the value associated to the ‟default” key.

An alternative (as long as Tabular data only allows simple strings in translations) using normal JSON syntax within values would have required escaping with a prepended backslash each one of these embedded double quotes (which would be less readable and more errorprone to edit with the current user interface for tabular data on this wiki):

[
    ...
    "en": "j' 'F' 'Y",
    ...
    "fr": "{ \"default\": \"j' 'F' 'Y\", \"d01\": \"j'<sup>er</sup> 'F' 'Y\" }",
    ...
]

In all cases, you must use ASCII single quotes (instead of ASCII double quotes) for marking litteral text to display as is, and you must use curly apostrophes (inside or outside marked litterals) for any apostrophe to display as is.

Data:I18n/MonthCases.tab

Grammatical cases of month names in different languages used by Module:DateI18n and Module:Complex_date.

See Also

Modules related to internationalization (i18n) of dates
{| class="wikitable sortable" border="1"
Module Name	Uses Module	Used by Module	Used by Template	Comment
Module:DateI18n	Module:I18n/date	Module:ISOdate	Template:Date	Create date string in any language
Module:ISOdate	Module:DateI18n	Module:Complex date	Template:ISOdate & Template:ISOyear	Parse YYYY-MM-DD date string
Module:Roman		Module:Complex date Module:Ordinal	Template:Roman	Create Roman numerals
Module:Ordinal	Module:I18n/ordinal Module:Roman	Module:Complex date	Template:Ordinal	Create Ordinal numerals
Module:Complex date	Module:I18n/complex date Module:ISOdate Module:Roman Module:Ordinal		Template:Other date (not deployed yet)	Create complex date phrases in many languages

|}