On Fri, 27 Feb 2026 21:58:56 GMT, Justin Lu <[email protected]> wrote:
> Locale APIs which accept BCP 47 tags use hyphen for multiple variant subtags.
> Locale APIs that accept multiple (non BCP 47 subtag) variants use
> underscores. For example,
>
> `Locale.of` supports multiple variants separated by underscore.
> `Locale.forLanguageTag` supports multiple variants separated by hyphen.
> `Locale.Builder.setLanguageTag` supports multiple variants separated by
> hyphen.
> `Locale.Builder.setVariant` supports multiple variants separated by either
> underscore or hyphen.
>
> The current wording is not detailed enough and implies both formats are
> interchangeable within `Locale`. This PR updates the wording to make this
> more apparent. Note that I left the constructor behavior out in the new
> wording as to not call attention to it.
src/java.base/share/classes/java/util/Locale.java line 182:
> 180: * BCP 47 language tags expect as such. However, {@link
> Locale.Builder#setVariant(String)}
> 181: * also supports underscore ('_') and {@link Locale#of(String, String,
> String)}
> 182: * only supports underscore ('_').</dd>
I think this behavior is to accommodate the JDK's own variants prior to BCP47.
So adding something like " for backward compatibility" would be helpful.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/29970#discussion_r2866530377
