symfony
diff --git a/‎components/intl.rst‎
Lines changed: 58 additions & 4 deletions b/‎components/intl.rst‎
Lines changed: 58 additions & 4 deletions
@@ -79,6 +79,24 @@ The ``Languages`` class provides access to the name of all languages::
     $language = Languages::getName('fr');
     // => 'French'
 
+You can also use the ISO 639-2 three-letter language codes instead of
+the ISO 639-1 two-letter codes, respectively called alpha3 and alpha2 codes::
+
+    use Symfony\Component\Intl\Languages;
+
+    \Locale::setDefault('en');
+
+    $languages = Languages::getAlpha3Names();
+    // ('languageCode' => 'languageName')
+    // => ['abk' => 'Abkhazian', 'ace' => 'Achinese', ...]
+
+    $language = Languages::getAlpha3Name('fra');
+    // => 'French'
+
+.. versionadded:: 4.4
+
+    The support for alpha3 codes was introduced in Symfony 4.4.
+
 All methods accept the translation locale as the last, optional parameter,
 which defaults to the current default locale::
 
@@ -94,6 +112,16 @@ to catching the exception, you can also check if a given language code is valid:
 
     $isValidLanguage = Languages::exists($languageCode);
 
+Or if you have a three-letter language code you want to check::
+
+    $isValidLanguage = Languages::alpha3CodeExists($alpha3Code);
+
+You may convert codes between two-letter ISO 639-1 (alpha2) and three-letter ISO 639-2 (alpha3) codes::
+
+    $alpha3Code = Languages::getAlpha3Code($alpha2Code);
+
+    $alpha2Code = Languages::getAlpha2Code($alpha3Code);
+
 The ``Scripts`` class provides access to the optional four-letter script code
 that can follow the language code according to the `Unicode ISO 15924 Registry`_
 (e.g. ``HANS`` in ``zh_HANS`` for simplified Chinese and ``HANT`` in ``zh_HANT``
@@ -129,34 +157,59 @@ Country Names
 ~~~~~~~~~~~~~
 
 The ``Countries`` class provides access to the name of all countries according
-to the `ISO 3166-1 alpha-2`_ list of officially recognized countries and
-territories::
+to the `ISO 3166-1 alpha-2`_ list and the `ISO 3166-1 alpha-3`_ list
+of officially recognized countries and territories::
 
     use Symfony\Component\Intl\Countries;
 
     \Locale::setDefault('en');
 
+    // Indexed with alpha-2
     $countries = Countries::getNames();
-    // ('countryCode' => 'countryName')
+    // ('alpha2Code' => 'countryName')
     // => ['AF' => 'Afghanistan', 'AX' => 'Åland Islands', ...]
 
+    // Indexed with alhpa-3
+    $countries = Countries::getAlpha3Names();
+    // ('alpha3Code' => 'countryName')
+    // => ['AFG' => 'Afghanistan', 'ALA' => 'Åland Islands', ...]
+
     $country = Countries::getName('GB');
     // => 'United Kingdom'
 
+    $country = Countries::getAlpha3Name('NOR');
+    // => 'Norway'
+
 All methods accept the translation locale as the last, optional parameter,
 which defaults to the current default locale::
 
     $countries = Countries::getNames('de');
     // => ['AF' => 'Afghanistan', 'EG' => 'Ägypten', ...]
 
+    $countries = Countries::getAlpha3Names('de');
+    // => ['AFG' => 'Afghanistan', 'EGY' => 'Ägypten', ...]
+
     $country = Countries::getName('GB', 'de');
     // => 'Vereinigtes Königreich'
 
+    $country = Countries::getAlpha3Name('GBR', 'de');
+    // => 'Vereinigtes Königreich'
+
 If the given country code doesn't exist, the methods trigger a
 :class:`Symfony\\Component\\Intl\\Exception\\MissingResourceException`. In addition
 to catching the exception, you can also check if a given country code is valid::
 
-    $isValidCountry = Countries::exists($countryCode);
+    $isValidCountry = Countries::exists($alpha2Code);
+
+Or if you have a alpha3 country code you want to check:
+
+    $isValidCountry = Countries::alpha3CodeExists($alpha3Code);
+
+You may convert codes between two-letter alpha2 and three-letter alpha3 codes::
+
+    $alpha3Code = Countries::getAlpha3Code($alpha2Code);
+
+    $alpha2Code = Countries::getAlpha2Code($alpha3Code);
 
 Locales
 ~~~~~~~
@@ -330,5 +383,6 @@ Learn more
 .. _ICU library: http://site.icu-project.org/
 .. _`Unicode ISO 15924 Registry`: https://www.unicode.org/iso15924/iso15924-codes.html
 .. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+.. _`ISO 3166-1 alpha-3`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
 .. _`UTC/GMT time offsets`: https://en.wikipedia.org/wiki/List_of_UTC_time_offsets
 .. _`daylight saving time (DST)`: https://en.wikipedia.org/wiki/Daylight_saving_time