add countryCode

[jack5505]

Thanks for your contribution to Apache Commons! Your help is appreciated!

Before you push a pull request, review this list:

• Read the contribution guidelines for this project.
• Read the ASF Generative Tooling Guidance if you use Artificial Intelligence (AI).
• I used AI to create any part of, or all of, this pull request.
• Run a successful build using the default Maven goal with mvn; that's mvn on the command line by itself.
• Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied. This may not always be possible, but it is a best-practice.
• Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
• Each commit in the pull request should have a meaningful subject line and body. Note that a maintainer may squash commits during the merge process.

[jack5505]

done

[jack5505]

why CI will happen error @garydgregory could you please give some advice what to do here thanks in advance

[garydgregory]

The Java 26-ea build is experimental and is allowed to fail.

[ppkarwasz]

@jack5505,

Thanks for this contribution! Before looking at the details, I’d like to understand your use case a bit better. Are you trying to construct Locale objects from ISO 3166-1 numeric codes, or do you need a general-purpose conversion utility between different ISO country code formats? That context would help evaluate whether this belongs in LocaleUtils.

A few observations from my side:

1. Scope of Locale support

   • Java’s Locale supports only ISO 3166-1 alpha-2 codes for regions, or UN M.49 numeric codes for macro-regions.
   • ISO 3166-1 alpha-3 and numeric country codes are not valid BCP 47 region subtags and therefore cannot be used directly in Locale.
   • This makes me question whether mapping alpha-2 <-> numeric belongs in LocaleUtils, which is focused on Locale-compatible operations.

2. Comparison with existing APIs

   • The proposed toNumeric() method could be seen as complementing Locale#getISO3Country() and Locale#getISO3Language(), which already expose ISO 3166-1 alpha-3 and ISO 639-2/3 codes.
   • However, these JDK methods appear to have very limited real-world usage. A scan across GitHub shows they are used mainly in thin wrappers or helper utilities that simply re-expose the same functionality, rather than being called directly in application logic (example search).
   • This lack of adoption suggests that demand for alpha-3 or numeric conversions is limited, and raises the question of whether Commons Lang is the right place to add this functionality.

3. Completeness of this PR

   • Right now the PR only covers alpha-2 <-> numeric. If the goal is to provide a general conversion utility, then it feels incomplete without alpha-2 <-> alpha-3, and possibly alpha-3 <-> numeric mappings.
   • Without the full picture, the API may be confusing or misleading to users who expect all three forms to be supported.

4. Data maintenance

   • The codes are currently hard-coded. That raises a long-term maintenance issue: ISO and UN occasionally update codes.
   • A more robust approach would be to generate the mapping from CLDR’s supplementalData.xml (where codeMappings contains alpha-2/alpha-3/numeric relationships). This is how the JDK itself sources its locale data, ensuring alignment with Unicode/CLDR.