getLocale,getLanguage, and docs
diff --git a/doc/index.md b/doc/index.md
index 18afafd..9187e57 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -20,7 +20,14 @@
# org.apache.cordova.globalization
This plugin obtains information and performs operations specific to the user's
-locale and timezone.
+locale, language, and timezone. Note the difference between locale and language:
+locale controls how numbers, dates, and times are displayed for a region, while
+language determines what language text appears as, independently of locale settings.
+Often developers use locale to set both settings, but there is no reason a user
+couldn't set her language to "English" but locale to "French", so that text is
+displayed in English but dates, times, etc., are displayed as they are in France.
+Unfortunately, most mobile platforms currently do not make a distinction between
+these settings.
## Installation
@@ -45,6 +52,93 @@
- navigator.globalization.getNumberPattern
- navigator.globalization.getCurrencyPattern
+## navigator.globalization.getPreferredLanguage
+
+Get the BCP 47 language tag for the client's current language.
+
+ navigator.globalization.getPreferredLanguage(successCallback, errorCallback);
+
+### Description
+
+Returns the BCP-47 compliant language identifier tag to the `successCallback`
+with a `properties` object as a parameter. That object should have a `value`
+property with a `String` value.
+
+If there is an error getting the language, then the `errorCallback`
+executes with a `GlobalizationError` object as a parameter. The
+error's expected code is `GlobalizationError.UNKNOWN_ERROR`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- iOS
+- Windows Phone 8
+
+### Example
+
+When the browser is set to the `en-US` language, this should display a
+popup dialog with the text `language: en-US`:
+
+ navigator.globalization.getPreferredLanguage(
+ function (language) {alert('language: ' + language.value + '\n');},
+ function () {alert('Error getting language\n');}
+ );
+
+### Android Quirks
+
+- Returns the ISO 639-1 two-letter language code, upper case ISO 3166-1
+country code and variant separated by hyphens. Examples: "en", "en-US", "US"
+
+### Windows Phone 8 Quirks
+
+- Returns the ISO 639-1 two-letter code for the current language.
+
+
+## navigator.globalization.getLocaleName
+
+Returns the BCP 47 compliant tag for the client's current locale setting.
+
+ navigator.globalization.getLocaleName(successCallback, errorCallback);
+
+### Description
+
+Returns the BCP 47 compliant locale identifier string to the `successCallback`
+with a `properties` object as a parameter. That object should have a `value`
+property with a `String` value. The locale tag will consist of a two-letter lower
+case language code, two-letter upper case country code, and (unspecified) variant
+code, separated by a hyphen.
+
+If there is an error getting the locale, then the `errorCallback`
+executes with a `GlobalizationError` object as a parameter. The
+error's expected code is `GlobalizationError.UNKNOWN_ERROR`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- iOS
+- Windows Phone 8
+
+### Example
+
+When the browser is set to the `en-US` locale, this displays a popup
+dialog with the text `locale: en-US`.
+
+ navigator.globalization.getLocaleName(
+ function (locale) {alert('locale: ' + locale.value + '\n');},
+ function () {alert('Error getting locale\n');}
+ );
+
+### Android Quirks
+
+- Java does not distinguish between a set "langauge" and set "locale," so this
+method is essentially the same as `navigator.globalizatin.getPreferredLanguage()`.
+
+### Windows Phone 8 Quirks
+
+- Returns the two-letter code defined in ISO 3166 for the current country/region.
+
## navigator.globalization.dateToString
@@ -61,7 +155,7 @@
If there is an error formatting the date, then the `errorCallback`
executes with a `GlobalizationError` object as a parameter. The
-error's expected code is `GlobalizationError.FORMATTING\_ERROR`.
+error's expected code is `GlobalizationError.FORMATTING_ERROR`.
The `options` parameter is optional, and its default values are:
@@ -80,7 +174,7 @@
### Example
-If the browser is set to the `en\_US` locale, this displays a popup
+If the browser is set to the `en_US` locale, this displays a popup
dialog with text similar to `date: 9/25/2012 4:21PM` using the default
options:
@@ -124,7 +218,7 @@
If there is an error obtaining the pattern, then the `errorCallback`
executes with a `GlobalizationError` object as a parameter. The
-error's expected code is `GlobalizationError.FORMATTING\_ERROR`.
+error's expected code is `GlobalizationError.FORMATTING_ERROR`.
### Supported Platforms
@@ -134,7 +228,7 @@
### Example
-When the browser is set to the `en\_US` locale and the selected
+When the browser is set to the `en_US` locale and the selected
currency is United States Dollars, this example displays a popup
dialog with text similar to the results that follow:
@@ -178,7 +272,7 @@
If there is an error obtaining the names, then the `errorCallback`
executes with a `GlobalizationError` object as a parameter. The
-error's expected code is `GlobalizationError.UNKNOWN\_ERROR`.
+error's expected code is `GlobalizationError.UNKNOWN_ERROR`.
The `options` parameter is optional, and its default values are:
@@ -197,7 +291,7 @@
### Example
-When the browser is set to the `en\_US` locale, this example displays
+When the browser is set to the `en_US` locale, this example displays
a series of twelve popup dialogs, one per month, with text similar to
`month: January`:
@@ -228,13 +322,13 @@
- __timezone__: The abbreviated name of the time zone on the client. _(String)_
-- __utc\_offset__: The current difference in seconds between the client's time zone and coordinated universal time. _(Number)_
+- __utc_offset__: The current difference in seconds between the client's time zone and coordinated universal time. _(Number)_
-- __dst\_offset__: The current daylight saving time offset in seconds between the client's non-daylight saving's time zone and the client's daylight saving's time zone. _(Number)_
+- __dst_offset__: The current daylight saving time offset in seconds between the client's non-daylight saving's time zone and the client's daylight saving's time zone. _(Number)_
If there is an error obtaining the pattern, the `errorCallback`
executes with a `GlobalizationError` object as a parameter. The
-error's expected code is `GlobalizationError.PATTERN\_ERROR`.
+error's expected code is `GlobalizationError.PATTERN_ERROR`.
The `options` parameter is optional, and defaults to the following values:
@@ -253,7 +347,7 @@
### Example
-When the browser is set to the `en\_US` locale, this example displays
+When the browser is set to the `en_US` locale, this example displays
a popup dialog with text such as `pattern: M/d/yyyy h:mm a`:
function checkDatePattern() {
@@ -291,7 +385,7 @@
If there is an error obtaining the pattern, then the `errorCallback`
executes with a `GlobalizationError` object as a parameter. The
-error's expected code is `GlobalizationError.UNKNOWN\_ERROR`.
+error's expected code is `GlobalizationError.UNKNOWN_ERROR`.
### Supported Platforms
@@ -302,7 +396,7 @@
### Example
-When the browser is set to the `en\_US` locale, this displays a
+When the browser is set to the `en_US` locale, this displays a
popup dialog with text similar to `day: 1`.
navigator.globalization.getFirstDayOfWeek(
@@ -311,42 +405,6 @@
);
-Get the string identifier for the client's current locale setting.
-
- navigator.globalization.getLocaleName(successCallback, errorCallback);
-
-### Description
-
-Returns the locale identifier string to the `successCallback` with a
-`properties` object as a parameter. That object should have a `value`
-property with a `String` value.
-
-If there is an error getting the locale, then the `errorCallback`
-executes with a `GlobalizationError` object as a parameter. The
-error's expected code is `GlobalizationError.UNKNOWN\_ERROR`.
-
-### Supported Platforms
-
-- Amazon Fire OS
-- Android
-- iOS
-- Windows Phone 8
-
-### Example
-
-When the browser is set to the `en\_US` locale, this displays a popup
-dialog with the text `locale: en\_US`.
-
- navigator.globalization.getLocaleName(
- function (locale) {alert('locale: ' + locale.value + '\n');},
- function () {alert('Error getting locale\n');}
- );
-
-
-### Windows Phone 8 Quirks
-
-- Returns the two-letter code defined in ISO 3166 for the current country/region.
-
## navigator.globalization.getNumberPattern
Returns a pattern string to format and parse numbers according to the client's user preferences.
@@ -376,7 +434,7 @@
If there is an error obtaining the pattern, then the `errorCallback`
executes with a `GlobalizationError` object as a parameter. The
-error's expected code is `GlobalizationError.PATTERN\_ERROR`.
+error's expected code is `GlobalizationError.PATTERN_ERROR`.
The `options` parameter is optional, and default values are:
@@ -393,7 +451,7 @@
### Example
-When the browser is set to the `en\_US` locale, this should display a
+When the browser is set to the `en_US` locale, this should display a
popup dialog with text similar to the results that follow:
navigator.globalization.getNumberPattern(
@@ -427,47 +485,6 @@
- The `fraction` property is not supported, and returns zero.
-## navigator.globalization.getPreferredLanguage
-
-Get the string identifier for the client's current language.
-
- navigator.globalization.getPreferredLanguage(successCallback, errorCallback);
-
-### Description
-
-Returns the BCP-47 compliant language identifier tag to the `successCallback`
-with a `properties` object as a parameter. That object should have a `value`
-property with a `String` value.
-
-If there is an error getting the language, then the `errorCallback`
-executes with a `GlobalizationError` object as a parameter. The
-error's expected code is `GlobalizationError.UNKNOWN\_ERROR`.
-
-### Supported Platforms
-
-- Amazon Fire OS
-- Android
-- iOS
-- Windows Phone 8
-
-### Example
-
-When the browser is set to the `en\_US` locale, this should display a
-popup dialog with the text `language: en_US`:
-
- navigator.globalization.getPreferredLanguage(
- function (language) {alert('language: ' + language.value + '\n');},
- function () {alert('Error getting language\n');}
- );
-
-### Android Quirks
-
-- Returns the ISO 639-1 two-letter language code, upper case ISO 3166-1
-country code and variant separated by underscores. Examples: "en", "en_US", "_US"
-
-### Windows Phone 8 Quirks
-
-- Returns the ISO 639-1 two-letter code for the current language.
## navigator.globalization.isDayLightSavingsTime
@@ -487,7 +504,7 @@
The inbound parameter `date` should be of type `Date`.
If there is an error reading the date, then the `errorCallback`
-executes. The error's expected code is `GlobalizationError.UNKNOWN\_ERROR`.
+executes. The error's expected code is `GlobalizationError.UNKNOWN_ERROR`.
### Supported Platforms
@@ -524,7 +541,7 @@
If there is an error formatting the number, then the `errorCallback`
executes with a `GlobalizationError` object as a parameter. The
-error's expected code is `GlobalizationError.FORMATTING\_ERROR`.
+error's expected code is `GlobalizationError.FORMATTING_ERROR`.
The `options` parameter is optional, and its default values are:
@@ -541,7 +558,7 @@
### Example
-When the browser is set to the `en\_US` locale, this displays a popup
+When the browser is set to the `en_US` locale, this displays a popup
dialog with text similar to `number: 3.142`:
navigator.globalization.numberToString(
@@ -592,7 +609,7 @@
If there is an error parsing the date string, then the `errorCallback`
executes with a `GlobalizationError` object as a parameter. The
-error's expected code is `GlobalizationError.PARSING\_ERROR`.
+error's expected code is `GlobalizationError.PARSING_ERROR`.
### Supported Platforms
@@ -603,7 +620,7 @@
### Example
-When the browser is set to the `en\_US` locale, this displays a
+When the browser is set to the `en_US` locale, this displays a
popup dialog with text similar to `month:8 day:25 year:2012`. Note
that the month integer is one less than the string, as the month
integer represents an array index.
@@ -638,7 +655,7 @@
If there is an error parsing the number string, then the
`errorCallback` executes with a `GlobalizationError` object as a
parameter. The error's expected code is
-`GlobalizationError.PARSING\_ERROR`.
+`GlobalizationError.PARSING_ERROR`.
The `options` parameter is optional, and defaults to the following
values:
@@ -656,7 +673,7 @@
### Example
-When the browser is set to the `en\_US` locale, this should display a
+When the browser is set to the `en_US` locale, this should display a
popup dialog with text similar to `number: 1234.56`:
navigator.globalization.stringToNumber(
@@ -674,10 +691,10 @@
### Properties
- __code__: One of the following codes representing the error type _(Number)_
- - GlobalizationError.UNKNOWN\_ERROR: 0
- - GlobalizationError.FORMATTING\_ERROR: 1
- - GlobalizationError.PARSING\_ERROR: 2
- - GlobalizationError.PATTERN\_ERROR: 3
+ - GlobalizationError.UNKNOWN_ERROR: 0
+ - GlobalizationError.FORMATTING_ERROR: 1
+ - GlobalizationError.PARSING_ERROR: 2
+ - GlobalizationError.PATTERN_ERROR: 3
- __message__: A text message that includes the error's explanation and/or details _(String)_
### Description
diff --git a/src/android/Globalization.java b/src/android/Globalization.java
index 612d731..ca9691e 100644
--- a/src/android/Globalization.java
+++ b/src/android/Globalization.java
@@ -132,24 +132,8 @@
return true;
}
/*
- * @Description: Returns the string identifier for the client's current locale setting
- *
- * @Return: JSONObject
- * Object.value {String}: The locale identifier
- *
- * @throws: GlobalizationError.UNKNOWN_ERROR
- */
- private JSONObject getLocaleName() throws GlobalizationError{
- JSONObject obj = new JSONObject();
- try{
- obj.put("value",Locale.getDefault().toString());//get the locale from the Android Device
- return obj;
- }catch(Exception e){
- throw new GlobalizationError(GlobalizationError.UNKNOWN_ERROR);
- }
- }
- /*
- * @Description: Returns a well-formed ITEF BCP 47 language tag representing this localestring identifier for the client's current locale
+ * @Description: Returns a well-formed ITEF BCP 47 language tag representing
+ * the locale identifier for the client's current locale
*
* @Return: String: The BCP 47 language tag for the current locale
*/
@@ -199,7 +183,28 @@
return bcp47Tag.toString();
}
/*
- * @Description: Returns the string identifier for the client's current language
+ * @Description: Returns the BCP 47 Unicode locale identifier for current locale setting
+ * The locale is defined by a language code, a country code, and a variant, separated
+ * by a hyphen, for example, "en-US", "fr-CA", etc.,
+ *
+ * @Return: JSONObject
+ * Object.value {String}: The locale identifier
+ *
+ * @throws: GlobalizationError.UNKNOWN_ERROR
+ */
+ private JSONObject getLocaleName() throws GlobalizationError{
+ JSONObject obj = new JSONObject();
+ try{
+ obj.put("value", toBcp47Language(Locale.getDefault()));
+ return obj;
+ }catch(Exception e){
+ throw new GlobalizationError(GlobalizationError.UNKNOWN_ERROR);
+ }
+ }
+ /*
+ * @Description: Returns the BCP 47 language tag for the client's
+ * current language. Currently in Android this is the same as locale,
+ * since Java does not distinguish between locale and language.
*
* @Return: JSONObject
* Object.value {String}: The language identifier
