The OpenJDK Quality Group is promoting the testing of FOSS projects with OpenJDK builds as a way to improve the overall quality of the release. This heads-up is part of a regular communication sent to the projects involved. To learn more about the program, and how-to join, please check here.

ISO 639 and BCP 47

BCP 47, first introduced in 1995, defines tags to identify languages and its primary subtag (the first of potentially multiple subtags) is drawn from the much older ISO 639 standard. ISO 639 itself evolved over time, though, particularly for these three languages:

• Hebrew:
  • old: iw
  • new: he
• Indonesian:
  • old: in
  • new: id
• Yiddish:
  • old: ji
  • new: yi

Past Preference

Before JDK 17, Java treated the old ISO-639 tags of these three languages as canonical (see Locale’s old documentation under Legacy language codes):

static void printLocales(String iso, String bcp) {
	System.out.println(Locale.forLanguageTag(iso) + " | " + Locale.forLanguageTag(bcp));
}

// on JDK < 17, the old tags are preferred:
public static void main(String[] args) {
	printLocales("iw", "he"); // ~> "iw | iw"
	printLocales("in", "id"); // ~> "in | in"
	printLocales("ji", "yi"); // ~> "ji | ji"
}

Transition

This changed in JDK 17 and since then the default behavior was to map to the new ISO 639 tags:

// on JDK 17+, the new tags are preferred:
public static void main(String[] args) {
	printLocales("iw", "he"); // ~> "he | he"
	printLocales("in", "id"); // ~> "id | id"
	printLocales("ji", "yi"); // ~> "yi | yi"
}

To allow applications to update to Java 17 and later without requiring immediate code changes, the temporary system property java.locale.useOldISOCodes was introduced. Setting it to true reverted to the behavior before Java 17.

New Preference

JDK 25 deprecated java.locale.useOldISOCodes (described in Locale’s updated documentation) and JDK 27 will remove it. Setting it will result in a warning:

WARNING: The system property "java.locale.useOldISOCodes" is no longer supported. Any specified value will be ignored.

Code that relies on java.locale.useOldISOCodes needs to be updated to consistently expect the new ISO 639 tags when querying Locale instances. It will remain possible to use the old tags to instantiate Locale instances for Hebrew, Indonesian, and Yiddish.