Return-Path: X-Original-To: apmail-cordova-commits-archive@www.apache.org Delivered-To: apmail-cordova-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 5007A10466 for ; Thu, 1 May 2014 16:45:57 +0000 (UTC) Received: (qmail 64215 invoked by uid 500); 1 May 2014 16:45:57 -0000 Delivered-To: apmail-cordova-commits-archive@cordova.apache.org Received: (qmail 64197 invoked by uid 500); 1 May 2014 16:45:56 -0000 Mailing-List: contact commits-help@cordova.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@cordova.apache.org Delivered-To: mailing list commits@cordova.apache.org Received: (qmail 64190 invoked by uid 99); 1 May 2014 16:45:56 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 01 May 2014 16:45:56 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id 3373C88B9BE; Thu, 1 May 2014 16:45:56 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: mrbillau@apache.org To: commits@cordova.apache.org Message-Id: X-Mailer: ASF-Git Admin Mailer Subject: git commit: getLocale,getLanguage, and docs Date: Thu, 1 May 2014 16:45:56 +0000 (UTC) Repository: cordova-plugin-globalization Updated Branches: refs/heads/CB-4602 69562f4d7 -> 693a6f236 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/CB-4602 Commit: 693a6f2365533db4843125a62163f65f11b0150d Parents: 69562f4 Author: mbillau Authored: Thu May 1 12:32:08 2014 -0400 Committer: mbillau 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