Summary

Clarify the expected syntax of multiple variants for java.util.Locale and java.util.Locale.Builder APIs.

Problem

For historical reasons, Locale (and its builder class) provide APIs which allow for hyphen, underscore, or both formats for multiple locale variants. The current wording implies that this format is interchangeable across all APIs within Locale. However, there is unique behavior depending on which API is used. 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.

Solution

Update the specification in the variant description under the Locale class description.

Specification

In the variant description under the Locale class description,

- *   uses hyphen ('-') as a delimiter, {@code Locale} is more lenient.</dd>
+ *   uses hyphen ('-') as a delimiter and APIs provided by {@code Locale} which accept
+ *   BCP 47 language tags expect as such. However, for backwards compatibility,
+ *   {@link Locale.Builder#setVariant(String)} also accepts underscore ('_').
+ *   {@link Locale#of(String, String, String)} accepts only underscore ('_').</dd>