RFR: 8357275: Locale.Builder.setLanguageTag should explicitly state extlangs are allowed [v2]

[Justin Lu]

On Tue, 20 May 2025 00:39:16 GMT, Naoto Sato <naoto at openjdk.org> wrote:

>> An exception is thrown when more than three extlang subtags are provided (ill-formed). The new wording is when an allowed amount of extlang subtags are provided (not ill-formed). For example,
>> 
>> `new Locale.Builder().setLanguageTag("zh-yue-gan-cmn-czh-CN").build()` // throws
>> `new Locale.Builder().setLanguageTag("zh-yue-gan-cmn-CN").build()` // ==> yue_CN
>> 
>> i.e. if one to three extlang subtags occur, discard extras. If more than 3 occur, then it is ill-formed, and the method is already specified to throw on ill-formed tags. (Edit: Forgot to adjust the example)
>
> OK. I would add these examples here too, which may be more helpful.

Actually, `Locale.Builder.setLanguageTag` should mention all of the conversions that are made on the language tag, not just _extlang_ specifically. I'll link to the conversions section in `Locale.forLanguageTag` instead.
I also adjusted the _extlang_ example in `forLanguageTag` to indicate that the 4 _extlang_ example is "ill-formed" which should imply `Locale.Builder.setLanguageTag` throws an exception for that respective example.

Please see https://github.com/openjdk/jdk/pull/25309/commits/2d70bf799ba1285d599067c3d174dd8bd227db1f.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/25309#discussion_r2098491604