cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From purplecabb...@apache.org
Subject [2/5] git commit: getLocale,getLanguage, and docs
Date Fri, 23 May 2014 06:08:35 GMT
getLocale,getLanguage, and docs


Project: http://git-wip-us.apache.org/repos/asf/cordova-plugin-globalization/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugin-globalization/commit/693a6f23
Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-globalization/tree/693a6f23
Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-globalization/diff/693a6f23

Branch: refs/heads/master
Commit: 693a6f2365533db4843125a62163f65f11b0150d
Parents: 69562f4
Author: mbillau <mike.billau@gmail.com>
Authored: Thu May 1 12:32:08 2014 -0400
Committer: mbillau <mike.billau@gmail.com>
Committed: Thu May 1 12:32:08 2014 -0400

----------------------------------------------------------------------
 doc/index.md                   | 223 +++++++++++++++++++-----------------
 src/android/Globalization.java |  43 ++++---
 2 files changed, 144 insertions(+), 122 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-plugin-globalization/blob/693a6f23/doc/index.md
----------------------------------------------------------------------
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 @@ locale and timezone.
 - 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 @@ The inbound `date` parameter should be of type `Date`.
 
 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 @@ The `options.selector` can be `date`, `time` or `date and time`.
 
 ### 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 @@ the ISO 4217 currency codes, for example 'USD'.
 
 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 @@ error's expected code is `GlobalizationError.FORMATTING\_ERROR`.
 
 ### 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 @@ the week, depending on the option selected.
 
 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 @@ The value of `options.item` can be `months` or `days`.
 
 ### 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 @@ a parameter contains the following properties:
 
 - __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 @@ time`.
 
 ### 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 @@ property with a `Number` value.
 
 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 @@ error's expected code is `GlobalizationError.UNKNOWN\_ERROR`.
 
 ### 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 @@ popup dialog with text similar to `day: 1`.
     );
 
 
-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 @@ as a parameter. That object contains the following properties:
 
 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 @@ The `options.type` can be `decimal`, `percent`, or `currency`.
 
 ### 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 @@ Results:
 
 - 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 @@ and `false` indicates that it is not.
 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 @@ property with a `String` value.
 
 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 @@ The `options.type` can be 'decimal', 'percent', or 'currency'.
 
 ### 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 @@ time`.
 
 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 @@ error's expected code is `GlobalizationError.PARSING\_ERROR`.
 
 ### 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 @@ as a parameter. That object should have a `value` property with a
 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 @@ The `options.type` can be `decimal`, `percent`, or `currency`.
 
 ### 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 @@ An object representing a error from the Globalization API.
 ### 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

http://git-wip-us.apache.org/repos/asf/cordova-plugin-globalization/blob/693a6f23/src/android/Globalization.java
----------------------------------------------------------------------
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 @@ public class Globalization extends CordovaPlugin  {
         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 @@ public class Globalization extends CordovaPlugin  {
         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


Mime
View raw message