RFR: 8378723: Locale variant delimiter is unclear
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. ------------- Commit messages: - init Changes: https://git.openjdk.org/jdk/pull/29970/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=29970&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8378723 Stats: 5 lines in 1 file changed: 3 ins; 0 del; 2 mod Patch: https://git.openjdk.org/jdk/pull/29970.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/29970/head:pull/29970 PR: https://git.openjdk.org/jdk/pull/29970
On Fri, 27 Feb 2026 21:58:56 GMT, Justin Lu <jlu@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
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.
Justin Lu has updated the pull request incrementally with one additional commit since the last revision: Describe basis for underscore support ------------- Changes: - all: https://git.openjdk.org/jdk/pull/29970/files - new: https://git.openjdk.org/jdk/pull/29970/files/bae0ef72..e161204b Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=29970&range=01 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=29970&range=00-01 Stats: 3 lines in 1 file changed: 0 ins; 0 del; 3 mod Patch: https://git.openjdk.org/jdk/pull/29970.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/29970/head:pull/29970 PR: https://git.openjdk.org/jdk/pull/29970
On Fri, 27 Feb 2026 23:11:36 GMT, Justin Lu <jlu@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.
Justin Lu has updated the pull request incrementally with one additional commit since the last revision:
Describe basis for underscore support
LGTM ------------- Marked as reviewed by naoto (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/29970#pullrequestreview-3877674950
On Fri, 27 Feb 2026 21:58:56 GMT, Justin Lu <jlu@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.
This pull request has now been integrated. Changeset: 86800eb2 Author: Justin Lu <jlu@openjdk.org> URL: https://git.openjdk.org/jdk/commit/86800eb2b34bd6ea7a77e7a9ac2f7dbce89c11fb Stats: 5 lines in 1 file changed: 3 ins; 0 del; 2 mod 8378723: Locale variant delimiter is unclear Reviewed-by: naoto ------------- PR: https://git.openjdk.org/jdk/pull/29970
participants (2)
-
Justin Lu
-
Naoto Sato