<i18n dev> RFR: 8378723: Locale variant delimiter is unclear

[Naoto Sato]

On Fri, 27 Feb 2026 21:58:56 GMT, Justin Lu <jlu at openjdk.org> 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