From db24b35a30cd28fda1f37d5e5e4a7241bdeeff3c Mon Sep 17 00:00:00 2001
From: Justin Lu <jlu@openjdk.org>
Date: Mon, 29 Jun 2026 16:27:54 +0000
Subject: [PATCH] 8387259: Clarify extlang in Locale composition description

Reviewed-by: naoto, iris
---
 src/java.base/share/classes/java/util/Locale.java | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/java.base/share/classes/java/util/Locale.java b/src/java.base/share/classes/java/util/Locale.java
index f600afbb007..462cd5755c2 100644
--- a/src/java.base/share/classes/java/util/Locale.java
+++ b/src/java.base/share/classes/java/util/Locale.java
@@ -120,9 +120,13 @@ import sun.util.locale.provider.TimeZoneNameUtility;
  *   {@code Locale} always canonicalizes to lower case.</dd>
  *
  *   <dd> <em>Syntax:</em> Well-formed {@code language} values have the form {@code [a-zA-Z]{2,8}}.</dd>
- *   <dd> <em> BCP 47 deviation:</em> this is not the full BCP 47 language production, since it excludes
+ *   <dd> <em> BCP 47 deviation:</em> {@code Locale} does not retain the
  *   <a href="https://www.rfc-editor.org/rfc/rfc5646#section-2.2.2">extlang</a>
- *   (as modern three-letter language codes are preferred).</dd>
+ *   subtag. This is because three-letter language codes are preferred over extlang
+ *   subtags. When a {@code Locale} is created from a language tag containing an
+ *   extlang subtag, the first extlang subtag is interpreted as the <i>language</i>
+ *   field. The primary language subtag and any subsequent extlang subtags
+ *   are ignored.</dd>
  *
  *   <dd> <em>Example:</em> "en" (English), "ja" (Japanese), "kok" (Konkani)</dd>
  *