Summary

Deprecate the use of java.locale.useOldISOCodes system property

Problem

The JDK has historically used outdated language codes for Hebrew iw, Indonesian in, and Yiddish ji by default. In JDK 17, we switched to their modern equivalents: he, id, and yi. To maintain compatibility, we introduced the java.locale.useOldISOCodes system property, allowing users to revert to the old codes if set to true. We now believe it is time to retire this property to simplify the codebase and reduce maintenance overhead.

Solution

Describe that the system property is deprecated in the java.util.Locale class description. A warning message will be issued if it is used, signaling its upcoming removal. A release after JDK25 will remove the property entirely.

Specification

Modify the class description of java.util.Locale class as follows:

--- a/src/java.base/share/classes/java/util/Locale.java
+++ b/src/java.base/share/classes/java/util/Locale.java
@@ -541,9 +541,11 @@
  * {@code true}, those three current language codes are mapped to their
  * backward compatible forms. The property is only read at Java runtime
  * startup and subsequent calls to {@code System.setProperty()} will
- * have no effect.
+ * have no effect. <b>As of Java SE 25, the use of the
+ * {@code java.locale.useOldISOCodes} system property is deprecated.
+ * This backwards compatible behavior will be removed in a future release of the JDK.</b>
  *
- * <p>The APIs added in 1.7 map between the old and new language codes,
+ * <p>The APIs added in Java SE 7 map between the old and new language codes,
  * maintaining the mapped codes internal to Locale (so that
  * {@code getLanguage} and {@code toString} reflect the mapped
  * code, which depends on the {@code java.locale.useOldISOCodes} system