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 usually drawn from the much older ISO 639-1 standard. There are exceptions, though, among them these three languages:

• Hebrew:
  • ISO 639: iw
  • BCP 47: he
• Indonesian:
  • ISO 639: in
  • BCP 47: id
• Yiddish:
  • ISO 639: ji
  • BCP 47: yi

Past Preference

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

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

// on JDK < 17, ISO 639 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 BCP 47 tags:

// on JDK 17+, BCP 47 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 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 BCP 47 tags when querying Locale instances. It will remain possible to use the ISO 639 tags to instantiate Locale instances for Hebrew, Indonesian, and Yiddish.