You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+14Lines changed: 14 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -20,6 +20,7 @@ This jQuery plugin enables complex culture-aware number and date parsing and for
20
20
<li><ahref="#dates">Date Formatting</a></li>
21
21
</ul>
22
22
23
+
<!-- using named anchors to workaround github stripping IDs from readme -->
23
24
<aname="why"></a>
24
25
<h2id="why">Why Globalization?</h2>
25
26
<p>
@@ -29,6 +30,7 @@ Each language, and the countries that speak that language, have different expect
29
30
A user using an application should be able to read and write dates and numbers in the format they are occustomed to. This plugin makes this possible, providing an API to convert user-entered numbers and dates -- in their own format -- into real numbers and dates, and conversely, to format numbers and dates into that format.
30
31
</p>
31
32
33
+
<aname="what"></a>
32
34
<h2id="what">What is a Culture?</h2>
33
35
<p>
34
36
jQuery.glob.js defines roughly 350 cultures. Part of the reason for this large number, besides there being a lot of cultures of the world, is because for some languages, expectations differ amoung the countries that speak it. English, for example, is an official language in dozens of countries. Despite the language being English, the expected date formatting still greatly differs between them.
@@ -40,11 +42,13 @@ So, it seems it is not useful to define cultures by their language alone. Nor is
40
42
Yet, it is perhaps unreasonable to expect application developers to cater to every possible language/country combination perfectly. It is important then to define so-called "neutral" cultures based on each language. This culture defines the most likely accepted set of rules by anyone speaking that language, whatever the country. Neutral cultures are defined only by their language code. For example, "es" is the neutral culture for Spanish.
41
43
</p>
42
44
45
+
<aname="cultures"></a>
43
46
<h2id="cultures">jQuery.cultures</h2>
44
47
<p>
45
48
A mapping of culture code to that culture. For example, jQuery.cultures.fr is an object representing the complete culture definition for the neutral French culture. Note that jQuery.glob.js alone only includes an English culture. To get additional cultures, you must seperately reference one or more of the culture scripts that come with it. See below on what fields are defined in each culture.
46
49
</p>
47
50
51
+
<aname="culture"></a>
48
52
<h2id="culture">jQuery.culture</h2>
49
53
<p>
50
54
This is set to the culture currently being used. This serves as the default culture if no culture is specified on the various parsing and formatting functions. For example, to change the current culture, set it to one of the available cultures:
An application that supports globalization and/or localization will need to have a way to determine the user's preference. Attempting to automatically determine the appropriate culture is useful, but it is good practice to always offer the user a choice, by whatever means.
In any case, if no match is found, the invariant culture is selected.
78
83
</p>
79
84
85
+
<aname="find"></a>
80
86
<h2id="find">jQuery.findClosestCulture</h2>
81
87
<p>
82
88
Just like preferCulture, but it returns the matching culture, if any, rather than setting jQuery.culture to it.
83
89
</p>
84
90
91
+
<aname="format"></a>
85
92
<h2id="format">jQuery.format(value, format, culture)</h2>
86
93
<p>
87
94
Formats a date or number according to the given format string and the given culture (or the current culture if not specified). See the section below on number and date formatting tokens for details on the available formats.
Parses a string representing a whole number in the given the radix (10 by default), taking into account any formatting rules followed by the given culture (or the current culture, if not specified).
Parses a string representing a floating point number in the given the radix (10 by default), taking into account any formatting rules followed by the given culture (or the current culture, if not specified).
@@ -124,6 +133,7 @@ jQuery.parseDate("1/2/2003"); // Sat Feb 01 2003
Gets or sets a localized value. This function allows you to extend the information available to a particular culture, and to easily retrieve it without worrying about finding the most appropriate culture. For example, to define the word "translate" in French:
Also note that localize() does not require loading the culture information script. You may use localize() for localization purposes without utilizing the parsing and formatting functions which depend on the cultures. If you do use both, it does not matter what order you include them in, either may be first -- the jQuery.glob.<code>.js script, or your own script which uses localize().
165
175
</p>
166
176
177
+
<aname="extend"></a>
167
178
<h2id="extend">Utilizing and Extending Cultures</h2>
168
179
<p>
169
180
The culture information included with each culture is mostly necessary for the parsing and formatting methods, but not all of it. For example, the the Native and English names for each culture is given, as well as a boolean indicating whether the language is right-to-left. This may be useful information for your own purposes. You may also add to the culture information directly if so desired. It is important to do so in a way that handles the fact that the culture info may not be provided, may not be provided yet, or may already be provided. Using jQuery's extend() method, it is possible to define a culture in a way that both defines if it does not exist and adds to it if it does exist.
Using this mechanism, the 'fr' culture will be created if it does not exist. And if it does, the given values will be added to it, taking care not to overwrite anything that is already defined (if you'd prefer to overwrite, you'd switch the last two arguments). When the jQuery.glob.fr.js script is eventually included, it too uses this technique, ensuring addition to the already-defined culture information.
Each culture is defined in its own script with the naming scheme jQuery.glob.<code>.js (along with its minified version, jQuery.glob.<code>.min.js). You may include any number of these scripts, making them available in the jQuery.cultures mapping. Including one of these scripts does NOT automatically make it the default culture selected with jQuery.culture.
When formatting a number with format(), the main purpose is to convert the number into a human readable string using the culture's standard grouping and decimal rules. The rules between cultures can vary a lot. For example, in some cultures, the grouping of numbers is done unevenly. In the "te-IN" culture (Telugu in India), groups have 3 digits and then 2 digits. The number 1000000 (one million) is written as "10,00,000". Some cultures do not group numbers at all.
Parsing with parseInt and parseFloat also accepts any of these formats.
407
420
</p>
408
421
422
+
<aname="dates"></a>
409
423
<h2id="dates">Date Formatting</h2>
410
424
<p>
411
425
Date formatting varies wildly by culture, not just in the spelling of month and day names, and the date separator, but by the expected order of the various date components, whether to use a 12 or 24 hour clock, and how months and days are abbreivated. Many cultures even include "genative" month names, which are different from the typical names and are used only in certain cases.
0 commit comments