Update doc references to refer to CLDR for region codes (#1638)

Update doc references to refer to CLDR and the page of CLDR codes where
appropriate - it used to say ISO country codes were used, but they aren't.

Also updated to refer to two *or three* letter language codes since they may be three letters (we use the shortest defined one for a language)

Updating comments about leadingDigits field at territory level as well.

cpp/src/phonenumbers/geocoding/mapping_file_provider.h

@@ -46,11 +46,11 @@ class MappingFileProvider {
 
   // Returns the name of the file that contains the mapping data for the
   // country_calling_code in the language specified, or an empty string if no
-  // such file can be found. language is a two-letter lowercase ISO language
-  // codes as defined by ISO 639-1. script is a four-letter titlecase (the first
-  // letter is uppercase and the rest of the letters are lowercase) ISO script
-  // codes as defined in ISO 15924. region is a two-letter uppercase ISO country
-  // codes as defined by ISO 3166-1.
+  // such file can be found. language is a two or three-letter lowercase
+  // language code as defined by ISO 639. script is a four-letter titlecase (the
+  // first letter is uppercase and the rest of the letters are lowercase) ISO
+  // script code as defined in ISO 15924. region is a two-letter uppercase ISO
+  // country code as defined by ISO 3166-1.
   const string& GetFileName(int country_calling_code, const string& language,
                             const string& script, const string& region, string*
                             filename) const;

cpp/src/phonenumbers/geocoding/phonenumber_offline_geocoder.h

@@ -93,7 +93,7 @@ class PhoneNumberOfflineGeocoder {
   //
   // user_region is the region code for a given user. This region will be
   // omitted from the description if the phone number comes from this region. It
-  // should be a two-letter uppercase ISO country code as defined by ISO 3166-1.
+  // should be a two-letter uppercase CLDR region code.
   string GetDescriptionForValidNumber(const PhoneNumber& number,
       const Locale& language, const string& user_region) const;
 
@@ -133,11 +133,11 @@ class PhoneNumberOfflineGeocoder {
 
   // Returns an area-level text description in the given language for the given
   // phone number, or an empty string.
-  // lang is a two-letter lowercase ISO language codes as defined by ISO 639-1.
+  // lang is a two or three-letter lowercase ISO language code as defined by ISO
+  // 639.
   // script is a four-letter titlecase (the first letter is uppercase and the
-  // rest of the letters are lowercase) ISO script codes as defined in ISO
-  // 15924.
-  // region should be a two-letter uppercase ISO country codes as defined by ISO
+  // rest of the letters are lowercase) ISO script code as defined in ISO 15924.
+  // region should be a two-letter uppercase ISO country code as defined by ISO
   // 3166-1.
   const char* GetAreaDescription(const PhoneNumber& number, const string& lang,
                                  const string& script,

cpp/src/phonenumbers/phonenumberutil.h

@@ -56,9 +56,9 @@ class PhoneNumberRegExpsAndMappings;
 class RegExp;
 
 // NOTE: A lot of methods in this class require Region Code strings. These must
-// be provided using ISO 3166-1 two-letter country-code format. The list of the
-// codes can be found here:
-// http://www.iso.org/iso/english_country_names_and_code_elements
+// be provided using CLDR two-letter region-code format. These should be in
+// upper-case. The list of the codes can be found here:
+// http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html
 
 class PhoneNumberUtil : public Singleton<PhoneNumberUtil> {
  private:

java/demo/war/phonenumberparser.jsp

@@ -20,7 +20,7 @@
       Specify a Default Country:
       <input type="text" name="defaultCountry" size="2">
           (<a href="http://www.iso.org/iso/english_country_names_and_code_elements">
-          ISO 3166-1 two-letter country code</a>)
+          CLDR two-letter region code</a>)
       <h2>Step 3</h2>
       <p>
       Specify a locale for phone number geocoding (Optional, defaults to en):

java/geocoder/src/com/google/i18n/phonenumbers/geocoding/PhoneNumberOfflineGeocoder.java

@@ -156,7 +156,7 @@ public class PhoneNumberOfflineGeocoder {
    * @param languageCode  the language code for which the description should be written
    * @param userRegion  the region code for a given user. This region will be omitted from the
    *     description if the phone number comes from this region. It should be a two-letter
-   *     uppercase ISO country code as defined by ISO 3166-1.
+   *     upper-case CLDR region code.
    * @return  a text description for the given language code for the given phone number, or an
    *     empty string if the number could come from multiple countries, or the country code is
    *     in fact invalid
@@ -203,7 +203,7 @@ public class PhoneNumberOfflineGeocoder {
    * @param languageCode  the language code for which the description should be written
    * @param userRegion  the region code for a given user. This region will be omitted from the
    *     description if the phone number comes from this region. It should be a two-letter
-   *     uppercase ISO country code as defined by ISO 3166-1.
+   *     uppercase CLDR region code.
    * @return  a text description for the given language code for the given phone number, or empty
    *     string if the number passed in is invalid or could belong to multiple countries
    */

java/internal/prefixmapper/src/com/google/i18n/phonenumbers/prefixmapper/PrefixFileReader.java

@@ -104,10 +104,10 @@ public class PrefixFileReader {
    * Returns a text description in the given language for the given phone number.
    *
    * @param number  the phone number for which we want to get a text description
-   * @param lang  two-letter lowercase ISO language codes as defined by ISO 639-1
+   * @param lang  two or three-letter lowercase ISO language code as defined by ISO 639
    * @param script  four-letter titlecase (the first letter is uppercase and the rest of the letters
-   *     are lowercase) ISO script codes as defined in ISO 15924
-   * @param region  two-letter uppercase ISO country codes as defined by ISO 3166-1
+   *     are lowercase) ISO script code as defined in ISO 15924
+   * @param region  two-letter uppercase ISO country code as defined by ISO 3166-1
    * @return  a text description in the given language for the given phone number, or an empty
    *     string if a description is not available
    */

java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java

@@ -44,9 +44,9 @@ import java.util.regex.Pattern;
  * our <a href="http://groups.google.com/group/libphonenumber-discuss/about">mailing list</a>.
  *
  * NOTE: A lot of methods in this class require Region Code strings. These must be provided using
- * ISO 3166-1 two-letter country-code format. These should be in upper-case. The list of the codes
+ * CLDR two-letter region-code format. These should be in upper-case. The list of the codes
  * can be found here:
- * http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm
+ * http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html
  *
  * @author Shaopeng Jia
  */

javascript/i18n/phonenumbers/asyoutypeformatter.js

@@ -47,8 +47,8 @@ goog.require('i18n.phonenumbers.metadata');
 /**
  * Constructs an AsYouTypeFormatter for the specific region.
  *
- * @param {string} regionCode the ISO 3166-1 two-letter region code that denotes
- *     the region where the phone number is being entered.
+ * @param {string} regionCode the CLDR two-letter region code that denotes the
+ *     region where the phone number is being entered.
  * @constructor
  */
 i18n.phonenumbers.AsYouTypeFormatter = function(regionCode) {

javascript/i18n/phonenumbers/demo-compiled.html

@@ -35,7 +35,7 @@ limitations under the License.
   <p>
   Specify a Default Country:
   <input type="text" name="defaultCountry" id="defaultCountry" size="2" />
-  (ISO 3166-1 two-letter country code)
+  (CLDR two-letter region code)
   </p>
   <p>
   Specify a Carrier Code:

javascript/i18n/phonenumbers/demo.html

@@ -44,7 +44,7 @@ limitations under the License.
   <p>
   Specify a Default Country:
   <input type="text" name="defaultCountry" id="defaultCountry" size="2" />
-  (ISO 3166-1 two-letter country code)
+  (CLDR two-letter region code)
   </p>
   <p>
   Specify a Carrier Code:

javascript/i18n/phonenumbers/phonenumberutil.js

@@ -20,11 +20,10 @@
  * Functionality includes formatting, parsing and validation.
  * (based on the java implementation).
  *
- * NOTE: A lot of methods in this class require Region Code strings. These must
- * be provided using ISO 3166-1 two-letter country-code format. These should be
- * in upper-case (but for compatibility lower-case is also allowed). The list of
- * the codes can be found here:
- * http://www.iso.org/iso/english_country_names_and_code_elements
+ * NOTE: A lot of methods in this class require Region Code strings. These must be provided using
+ * CLDR two-letter region-code format. These should be in upper-case. The list of the codes
+ * can be found here:
+ * http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html
  *
  * Credits to Nikolaos Trogkanis for original implementation.
  */
@@ -1434,7 +1433,7 @@ i18n.phonenumbers.PhoneNumberUtil.prototype.isNumberGeographical =
 /**
  * Helper function to check region code is not unknown or null.
  *
- * @param {?string} regionCode the ISO 3166-1 two-letter region code.
+ * @param {?string} regionCode the CLDR two-letter region code.
  * @return {boolean} true if region code is valid.
  * @private
  */
@@ -3094,7 +3093,7 @@ i18n.phonenumbers.PhoneNumberUtil.prototype.getNddPrefixForRegion = function(
  * Checks if this is a region under the North American Numbering Plan
  * Administration (NANPA).
  *
- * @param {?string} regionCode the ISO 3166-1 two-letter region code.
+ * @param {?string} regionCode the CLDR two-letter region code.
  * @return {boolean} true if regionCode is one of the regions under NANPA.
  */
 i18n.phonenumbers.PhoneNumberUtil.prototype.isNANPACountry =

pending_code_changes.txt

@@ -1 +1,8 @@
-
+Code changes:
+ - Doc changes to update references to ISO country codes to CLDR region codes,
+   which are what we actually use. Notice in some of the mapper files the
+   country code is still the ISO one, because it's used as part of a description
+   of a language only (e.g. zh-TW vs zh-CN). Edited the language comments there
+   since they can be two *or* three letters (c.f. fil for filipino). Also edited
+   the comment for leadingDigits at the territory level in the
+   phonemetadata.proto file.

resources/PhoneNumberAlternateFormats.xml

@@ -30,12 +30,12 @@
      mainCountryForCode set to true in PhoneNumberMetadata.xml should be present
      here.
 
-     Note: Territories are in alphabetical order by their IDs, which are based on ISO 3166-1
-           two-letter country codes. The country names in the comments are the official short names
-           in English according to ISO 3166-1.
+     Note: Territories are in alphabetical order by their IDs, which are based on CLDR
+           two-letter region codes (or are set to "001" for non-geographical entities, which
+           represents "World" in the UN M.49 standard). The country names in the comments are the
+           official short names in English according to CLDR.
 
-     For more information on what each element represents, see
-     resources/phonemetadata.proto
+     For more information on what each element represents, see resources/phonemetadata.proto
 -->
 
 <!DOCTYPE phoneNumberMetadata [

resources/PhoneNumberMetadata.xml

@@ -15,13 +15,12 @@
      @author: Shaopeng Jia
 
      Metadata on Phone Number Plan and formatting rules
-     Note: Territories are in alphabetical order by their IDs, which are based on ISO 3166-1
-           two-letter country codes (or are set to "001" for non-geographical entities, which
+     Note: Territories are in alphabetical order by their IDs, which are based on CLDR
+           two-letter region codes (or are set to "001" for non-geographical entities, which
            represents "World" in the UN M.49 standard). The country names in the comments are the
-           official short names in English according to ISO 3166-1.
+           official short names in English according to CLDR.
 
-     For more information on what each element represents, see
-     resources/phonemetadata.proto
+     For more information on what each element represents, see resources/phonemetadata.proto
 
      Note that if you want to add validation metadata, the generalDesc nationalNumberPattern and
      possibleNumberPattern must be provided. If this is missing, then the country will be

resources/phonemetadata.proto

@@ -171,11 +171,11 @@ message PhoneMetadata {
   // nationally.
   optional PhoneNumberDesc no_international_dialling = 24;
 
-  // The ISO 3166-1 alpha-2 representation of a country/region, with the
-  // exception of "country calling codes" used for non-geographical entities,
-  // such as Universal International Toll Free Number (+800). These are all
-  // given the ID "001", since this is the numeric region code for the world
-  // according to UN M.49: http://en.wikipedia.org/wiki/UN_M.49
+  // The CLDR 2-letter representation of a country/region, with the exception of
+  // "country calling codes" used for non-geographical entities, such as
+  // Universal International Toll Free Number (+800). These are all given the ID
+  // "001", since this is the numeric region code for the world according to UN
+  // M.49: http://en.wikipedia.org/wiki/UN_M.49
   required string id = 9;
 
   // The country calling code that one would dial from overseas when trying to
@@ -282,10 +282,14 @@ message PhoneMetadata {
 
   // This field is populated only for countries or regions that share a country
   // calling code. If a number matches this pattern, it could belong to this
-  // region. This is not intended as a replacement for IsValidForRegion, and
-  // does not mean the number must come from this region (for example, 800
-  // numbers are valid for all NANPA countries.) This field should be a regular
-  // expression of the expected prefix match.
+  // region. This is not intended as a replacement for IsValidForRegion since a
+  // matching prefix is insufficient for a number to be valid. Furthermore, it
+  // does not contain all the prefixes valid for a region - for example, 800
+  // numbers are valid for all NANPA countries and are hence not listed here.
+  // This field should be a regular expression of the expected prefix match.
+  // It is used merely as a short-cut for working out which region a number
+  // comes from in the case that there is only one, so leading_digit prefixes
+  // should not overlap.
   optional string leading_digits = 23;
 
   // The leading zero in a phone number is meaningful in some countries (e.g.