Skip to content

Documented the new Intl classes #11443

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Documented the new Intl classes #11443

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
483e43d
Documented the new Intl classes
javiereguiluz Apr 16, 2019
824edf2
Use HTTPS
javiereguiluz Apr 17, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 73 additions & 45 deletions components/intl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,125 +209,152 @@ locale will be merged. In order to suppress this behavior, the last parameter
Accessing ICU Data
------------------

The ICU data is located in several "resource bundles". You can access a PHP
wrapper of these bundles through the static
:class:`Symfony\\Component\\Intl\\Intl` class. At the moment, the following
data is supported:
This component provides the following ICU data:

* `Language and Script Names`_
* `Country Names`_
* `Country and Region Names`_
* `Locales`_
* `Currencies`_

Language and Script Names
~~~~~~~~~~~~~~~~~~~~~~~~~

The translations of language and script names can be found in the language
bundle::
The ``Languages`` class provides access to the name of all languages::

use Symfony\Component\Intl\Intl;
use Symfony\Component\Intl\Languages;

\Locale::setDefault('en');

$languages = Intl::getLanguageBundle()->getLanguageNames();
$languages = Languages::getNames();
// => ['ab' => 'Abkhazian', ...]

$language = Intl::getLanguageBundle()->getLanguageName('de');
$language = Languages::getName('de');
// => 'German'

$language = Intl::getLanguageBundle()->getLanguageName('de', 'AT');
$language = Languages::getName('de', 'AT');
// => 'Austrian German'

$scripts = Intl::getLanguageBundle()->getScriptNames();
All methods accept the translation locale as the last, optional parameter,
which defaults to the current default locale::

$languages = Languages::getNames('de');
// => ['ab' => 'Abchasisch', ...]

.. versionadded:: 4.3

The ``Languages`` class was introduced in Symfony 4.3.

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``
for traditional Chinese)::

use Symfony\Component\Intl\Scripts;

\Locale::setDefault('en');

$scripts = Scripts::getNames();
// => ['Arab' => 'Arabic', ...]

$script = Intl::getLanguageBundle()->getScriptName('Hans');
$script = Scripts::getName('Hans');
// => 'Simplified'

All methods accept the translation locale as the last, optional parameter,
which defaults to the current default locale::
.. versionadded:: 4.3

$languages = Intl::getLanguageBundle()->getLanguageNames('de');
// => ['ab' => 'Abchasisch', ...]
The ``Scrcipts`` class was introduced in Symfony 4.3.

.. _country-names:

Country Names
~~~~~~~~~~~~~
Country and Region Names
~~~~~~~~~~~~~~~~~~~~~~~~

The translations of country names can be found in the region bundle::
In the world there are some territorial disputes that make it hard to define
what a country is. That's why the Intl component provides a ``Regions`` class
instead of a ``Countries`` class::

use Symfony\Component\Intl\Intl;
use Symfony\Component\Intl\Regions;

\Locale::setDefault('en');

$countries = Intl::getRegionBundle()->getCountryNames();
$countries = Regions::getNames();
// => ['AF' => 'Afghanistan', ...]

$country = Intl::getRegionBundle()->getCountryName('GB');
$country = Regions::getName('GB');
// => 'United Kingdom'

All methods accept the translation locale as the last, optional parameter,
which defaults to the current default locale::

$countries = Intl::getRegionBundle()->getCountryNames('de');
$countries = Regions::getNames('de');
// => ['AF' => 'Afghanistan', ...]

.. versionadded:: 4.3

The ``Regions`` class was introduced in Symfony 4.3.

Locales
~~~~~~~

The translations of locale names can be found in the locale bundle::
A locale is the combination of a language and a region. For example, "Chinese"
is the language and ``zh_Hans_MO`` is the locale for "Chinese" (language) +
"Simplified" (script) + "Macau SAR China" (region). The ``Locales`` class
provides access to the name of all locales::

use Symfony\Component\Intl\Intl;
use Symfony\Component\Intl\Locales;

\Locale::setDefault('en');

$locales = Intl::getLocaleBundle()->getLocaleNames();
$locales = Locales::getNames();
// => ['af' => 'Afrikaans', ...]

$locale = Intl::getLocaleBundle()->getLocaleName('zh_Hans_MO');
$locale = Locales::getName('zh_Hans_MO');
// => 'Chinese (Simplified, Macau SAR China)'

All methods accept the translation locale as the last, optional parameter,
which defaults to the current default locale::

$locales = Intl::getLocaleBundle()->getLocaleNames('de');
$locales = Locales::getNames('de');
// => ['af' => 'Afrikaans', ...]

.. versionadded:: 4.3

The ``Locales`` class was introduced in Symfony 4.3.

Currencies
~~~~~~~~~~

The translations of currency names and other currency-related information can
be found in the currency bundle::
The ``Currencies`` class provides access to the name of all currencies as well
as some of their information (symbol, fraction digits, etc.)::

use Symfony\Component\Intl\Intl;
use Symfony\Component\Intl\Currencies;

\Locale::setDefault('en');

$currencies = Intl::getCurrencyBundle()->getCurrencyNames();
$currencies = Currencies::getNames();
// => ['AFN' => 'Afghan Afghani', ...]

$currency = Intl::getCurrencyBundle()->getCurrencyName('INR');
$currency = Currencies::getName('INR');
// => 'Indian Rupee'

$symbol = Intl::getCurrencyBundle()->getCurrencySymbol('INR');
$symbol = Currencies::getSymbol('INR');
// => '₹'

$fractionDigits = Intl::getCurrencyBundle()->getFractionDigits('INR');
$fractionDigits = Currencies::getFractionDigits('INR');
// => 2

$roundingIncrement = Intl::getCurrencyBundle()->getRoundingIncrement('INR');
$roundingIncrement = Currencies::getRoundingIncrement('INR');
// => 0

All methods (except for
:method:`Symfony\\Component\\Intl\\ResourceBundle\\CurrencyBundleInterface::getFractionDigits`
and
:method:`Symfony\\Component\\Intl\\ResourceBundle\\CurrencyBundleInterface::getRoundingIncrement`)
accept the translation locale as the last, optional parameter, which defaults
to the current default locale::
All methods (except for ``getFractionDigits()`` and ``getRoundingIncrement()``)
accept the translation locale as the last, optional parameter, which defaults to
the current default locale::

$currencies = Intl::getCurrencyBundle()->getCurrencyNames('de');
$currencies = Currencies::getNames('de');
// => ['AFN' => 'Afghanische Afghani', ...]

That's all you need to know for now. Have fun coding!
.. versionadded:: 4.3

The ``Currencies`` class was introduced in Symfony 4.3.

Learn more
----------
Expand All @@ -346,3 +373,4 @@ Learn more
.. _intl extension: https://php.net/manual/en/book.intl.php
.. _install the intl extension: https://php.net/manual/en/intl.setup.php
.. _ICU library: http://site.icu-project.org/
.. _`Unicode ISO 15924 Registry`: http://www.unicode.org/iso15924/iso15924-codes.html