8378723: Locale variant delimiter is unclear

Justin Lu · Justin Lu · commit 86800eb2b34b · 2026-03-03T17:11:17.000Z
Reviewed-by: naoto
diff --git a/src/java.base/share/classes/java/util/Locale.java b/src/java.base/share/classes/java/util/Locale.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2025, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2026, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -176,7 +176,10 @@
  *   SUBTAG (('_'|'-') SUBTAG)*} where {@code SUBTAG =
  *   [0-9][0-9a-zA-Z]{3} | [0-9a-zA-Z]{5,8}}.</dd>
  *   <dd> <em>BCP 47 deviation:</em> BCP 47 only
- *   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>
  *
  *   <dd> <em>Example:</em> "polyton" (Polytonic Greek), "POSIX"</dd>
  *

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`/*`
`2`		`- * Copyright (c) 1996, 2025, Oracle and/or its affiliates. All rights reserved.`
	`2`	`+ * Copyright (c) 1996, 2026, Oracle and/or its affiliates. All rights reserved.`
`3`	`3`	`* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.`
`4`	`4`	`*`
`5`	`5`	`* This code is free software; you can redistribute it and/or modify it`
`@@ -176,7 +176,10 @@`
`176`	`176`	`* SUBTAG (('_'\|'-') SUBTAG)*} where {@code SUBTAG =`
`177`	`177`	`* [0-9][0-9a-zA-Z]{3} \| [0-9a-zA-Z]{5,8}}.</dd>`
`178`	`178`	`* <dd> <em>BCP 47 deviation:</em> BCP 47 only`
`179`		`- * uses hyphen ('-') as a delimiter, {@code Locale} is more lenient.</dd>`
	`179`	`+ * uses hyphen ('-') as a delimiter and APIs provided by {@code Locale} which accept`
	`180`	`+ * BCP 47 language tags expect as such. However, for backwards compatibility,`
	`181`	`+ * {@link Locale.Builder#setVariant(String)} also accepts underscore ('_').`
	`182`	`+ * {@link Locale#of(String, String, String)} accepts only underscore ('_').</dd>`
`180`	`183`	`*`
`181`	`184`	`* <dd> <em>Example:</em> "polyton" (Polytonic Greek), "POSIX"</dd>`
`182`	`185`	`*`