Summary

Locale.Builder.setLanguageTag(String) should make apparent the conversions made on the String input.

Problem

Locale.forLanguageTag(String) performs a number of conversions on the language tag argument. Locale.Builder.setLanguageTag(String) similarly performs these conversions, but this is not apparent in the specification at all.

Additionally, BCP 47 defines a maximum of three extlang subtags. The behavior when a languageTag exceeds this limit is not clear, and should be specified:

Locale.Builder.setLanguageTag(String) throws an exception.

Locale.forLanguageTag(String) discards subsequent subtags.

Solution

Update the specification for Locale.Builder.setLanguageTag(String) to link to the full list of conversions.

Update the conversions section so that it is clear there is a limit of three extlang subtags.

Specification

In Locale.forLanguageTag,

     *     loc.getExtension('x'); // returns "urp"
      * }
      *
-     * <li>When the languageTag argument contains an extlang subtag,
-     * the first such subtag is used as the language, and the primary
-     * language subtag and other extlang subtags are ignored:
+     * <li> BCP 47 language tags permit up to three extlang subtags. However,
+     * the second and third extlang subtags are always ignored. As such,
+     * the first extlang subtag in {@code languageTag} is used as the language,
+     * and the primary language subtag and other extlang subtags are ignored.
+     * Language tags that exceed three extlang subtags are considered
+     * ill-formed starting at the offending extlang subtag.
      *
      * {@snippet lang=java :
      *     Locale.forLanguageTag("ar-aao").getLanguage(); // returns "aao"
      *     Locale.forLanguageTag("en-abc-def-us").toString(); // returns "abc_US"
+     *     Locale.forLanguageTag("zh-yue-gan-cmn-czh-CN").toString();
+     *     // returns "yue"; the rest of the tag is considered ill-formed
      * }
      *
      * <li>Case is normalized except for variant tags, which are left

In Locale.Builder.setLanguageTag,

          * just discards ill-formed and following portions of the
          * tag).
          *
+         * <p>See {@link Locale##langtag_conversions converions} for a full list
+         * of conversions that are performed on {@code languageTag}.
+         *
          * @param languageTag the language tag
          * @return This builder.
          * @throws IllformedLocaleException if {@code languageTag} is ill-formed