Comment changes to clarify which language code to use where there are two. (#1776)

cpp/src/phonenumbers/geocoding/mapping_file_provider.h

@@ -46,11 +46,14 @@ 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 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.
+  // such file can be found.
+  // language is a two or three-letter lowercase language code as defined by ISO
+  // 639. Note that where two different language codes exist (e.g. 'he' and 'iw'
+  // for Hebrew) we use the one that Java/Android canonicalized on ('iw' in this
+  // case).
+  // 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

@@ -134,7 +134,9 @@ 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 or three-letter lowercase ISO language code as defined by ISO
-  // 639.
+  // 639. Note that where two different language codes exist (e.g. 'he' and 'iw'
+  // for Hebrew) we use the one that Java/Android canonicalized on ('iw' in this
+  // case).
   // 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 should be a two-letter uppercase ISO country code as defined by ISO

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

@@ -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 CLDR region code.
+   *     upper-case 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/MappingFileProvider.java

@@ -145,7 +145,9 @@ public class MappingFileProvider implements Externalizable {
    *
    * @param countryCallingCode  the country calling code of phone numbers which the data file
    *     contains
-   * @param language  two-letter lowercase ISO language codes as defined by ISO 639-1
+   * @param language  two or three-letter lowercase ISO language codes as defined by ISO 639. Note
+   *     that where two different language codes exist (e.g. 'he' and 'iw' for Hebrew) we use the
+   *     one that Java/Android canonicalized on ('iw' in this case).
    * @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

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

@@ -104,7 +104,9 @@ 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 or three-letter lowercase ISO language code as defined by ISO 639
+   * @param language  two or three-letter lowercase ISO language codes as defined by ISO 639. Note
+   *     that where two different language codes exist (e.g. 'he' and 'iw' for Hebrew) we use the
+   *     one that Java/Android canonicalized on ('iw' in this case).
    * @param script  four-letter titlecase (the first letter is uppercase and the rest of the letters
    *     are lowercase) ISO script code as defined in ISO 15924
    * @param region  two-letter uppercase ISO country code as defined by ISO 3166-1
@@ -112,18 +114,18 @@ public class PrefixFileReader {
    *     string if a description is not available
    */
   public String getDescriptionForNumber(
-      PhoneNumber number, String lang, String script, String region) {
+      PhoneNumber number, String language, String script, String region) {
     int countryCallingCode = number.getCountryCode();
     // As the NANPA data is split into multiple files covering 3-digit areas, use a phone number
     // prefix of 4 digits for NANPA instead, e.g. 1650.
     int phonePrefix = (countryCallingCode != 1)
         ? countryCallingCode : (1000 + (int) (number.getNationalNumber() / 10000000));
     PhonePrefixMap phonePrefixDescriptions =
-        getPhonePrefixDescriptions(phonePrefix, lang, script, region);
+        getPhonePrefixDescriptions(phonePrefix, language, script, region);
     String description = (phonePrefixDescriptions != null)
         ? phonePrefixDescriptions.lookup(number) : null;
     // When a location is not available in the requested language, fall back to English.
-    if ((description == null || description.length() == 0) && mayFallBackToEnglish(lang)) {
+    if ((description == null || description.length() == 0) && mayFallBackToEnglish(language)) {
       PhonePrefixMap defaultMap = getPhonePrefixDescriptions(phonePrefix, "en", "", "");
       if (defaultMap == null) {
         return "";