1The Intl Extension
2==================
3
4The *Intl* extensions provides the ``localizeddate``, ``localizednumber`` and ``localizedcurrency`` filters.
5
6Installation
7------------
8
9First, :ref:`install the Extensions library<extensions-install>`. Next, add
10the extension to Twig::
11
12    $twig->addExtension(new Twig_Extensions_Extension_Intl());
13
14``localizeddate``
15-----------------
16
17Use the ``localizeddate`` filter to format dates into a localized string
18representating the date.
19
20.. code-block:: jinja
21
22    {{ post.published_at|localizeddate('medium', 'none', locale) }}
23
24The ``localizeddate`` filter accepts strings (it must be in a format supported
25by the `strtotime`_ function), `DateTime`_ instances, or `Unix timestamps`_.
26
27.. note::
28
29    Internally, Twig uses the PHP `IntlDateFormatter::create()`_ function for
30    the date.
31
32Arguments
33~~~~~~~~~
34
35* ``date_format``: The date format. Choose one of these formats:
36
37  * 'none':   `IntlDateFormatter::NONE`_
38  * 'short':  `IntlDateFormatter::SHORT`_
39  * 'medium': `IntlDateFormatter::MEDIUM`_
40  * 'long':   `IntlDateFormatter::LONG`_
41  * 'full':   `IntlDateFormatter::FULL`_
42
43* ``time_format``: The time format. Same formats possible as above.
44
45* ``locale``: The locale used for the format. If ``NULL`` is given, Twig will
46  use ``Locale::getDefault()``
47
48* ``timezone``: The date timezone
49
50* ``format``: Optional pattern to use when formatting or parsing. Possible
51  patterns are documented in the `ICU user guide`_.
52
53* ``calendar``: Calendar to use for formatting. The default value is 'gregorian',
54  which corresponds to IntlDateFormatter::GREGORIAN. Choose one of these formats:
55
56  * 'gregorian':   `IntlDateFormatter::GREGORIAN`_
57  * 'traditional':  `IntlDateFormatter::TRADITIONAL`_
58
59For the following calendars should use 'traditional':
60    * Japanese
61    * Buddhist
62    * Chinese
63    * Persian
64    * Indian
65    * Islamic
66    * Hebrew
67    * Coptic
68    * Ethiopic
69
70Also for non-Gregorian calendars need to be specified in locale.
71Examples might include locale="fa_IR@calendar=PERSIAN".
72
73
74``localizednumber``
75-------------------
76
77Use the ``localizednumber`` filter to format numbers into a localized string
78representating the number.
79
80.. code-block:: jinja
81
82    {{ product.quantity|localizednumber }}
83
84.. note::
85
86    Internally, Twig uses the PHP `NumberFormatter::create()`_ function for
87    the number.
88
89Arguments
90~~~~~~~~~
91
92* ``style``: Optional number format (default: 'decimal'). Choose one of these formats:
93
94  * 'decimal':    `NumberFormatter::DECIMAL`_
95  * 'currency':   `NumberFormatter::CURRENCY`_
96  * 'percent':    `NumberFormatter::PERCENT`_
97  * 'scientific': `NumberFormatter::SCIENTIFIC`_
98  * 'spellout':   `NumberFormatter::SPELLOUT`_
99  * 'ordinal':    `NumberFormatter::ORDINAL`_
100  * 'duration':   `NumberFormatter::DURATION`_
101
102* ``type``: Optional formatting type to use (default: 'default'). Choose one of these types:
103
104  * 'default':  `NumberFormatter::TYPE_DEFAULT`_
105  * 'int32':    `NumberFormatter::TYPE_INT32`_
106  * 'int64':    `NumberFormatter::TYPE_INT64`_
107  * 'double':   `NumberFormatter::TYPE_DOUBLE`_
108  * 'currency': `NumberFormatter::TYPE_CURRENCY`_
109
110* ``locale``: The locale used for the format. If ``NULL`` is given, Twig will
111  use ``Locale::getDefault()``
112
113``localizedcurrency``
114---------------------
115
116Use the ``localizedcurrency`` filter to format a currency value into a localized string.
117
118.. code-block:: jinja
119
120    {{ product.price|localizedcurrency('EUR') }}
121
122.. note::
123
124    Internally, Twig uses the PHP `NumberFormatter::create()`_ function for
125    the number.
126
127Arguments
128~~~~~~~~~
129
130* ``currency``: The 3-letter ISO 4217 currency code indicating the currency to use.
131
132* ``locale``: The locale used for the format. If ``NULL`` is given, Twig will
133  use ``Locale::getDefault()``
134
135
136.. _`strtotime`:                      http://php.net/strtotime
137.. _`DateTime`:                       http://php.net/DateTime
138.. _`Unix timestamps`:                http://en.wikipedia.org/wiki/Unix_time
139.. _`IntlDateFormatter::create()`:    http://php.net/manual/en/intldateformatter.create.php
140.. _`IntlDateFormatter::NONE`:        http://php.net/manual/en/class.intldateformatter.php#intldateformatter.constants.none
141.. _`IntlDateFormatter::SHORT`:       http://php.net/manual/en/class.intldateformatter.php#intldateformatter.constants.short
142.. _`IntlDateFormatter::MEDIUM`:      http://php.net/manual/en/class.intldateformatter.php#intldateformatter.constants.medium
143.. _`IntlDateFormatter::LONG`:        http://php.net/manual/en/class.intldateformatter.php#intldateformatter.constants.long
144.. _`IntlDateFormatter::FULL`:        http://php.net/manual/en/class.intldateformatter.php#intldateformatter.constants.full
145.. _`IntlDateFormatter::GREGORIAN`:   http://php.net/IntlDateFormatter#intldateformatter.constants.gregorian
146.. _`IntlDateFormatter::TRADITIONAL`: http://php.net/IntlDateFormatter#intldateformatter.constants.traditional
147.. _`ICU user guide`:                 http://userguide.icu-project.org/formatparse/datetime
148.. _`NumberFormatter::create()`:      http://php.net/manual/en/numberformatter.create.php
149.. _`NumberFormatter::DECIMAL`:       http://php.net/manual/en/class.numberformatter.php#numberformatter.constants.decimal
150.. _`NumberFormatter::CURRENCY`:      http://php.net/manual/en/class.numberformatter.php#numberformatter.constants.currency
151.. _`NumberFormatter::PERCENT`:       http://php.net/manual/en/class.numberformatter.php#numberformatter.constants.percent
152.. _`NumberFormatter::SCIENTIFIC`:    http://php.net/manual/en/class.numberformatter.php#numberformatter.constants.scientific
153.. _`NumberFormatter::SPELLOUT`:      http://php.net/manual/en/class.numberformatter.php#numberformatter.constants.spellout
154.. _`NumberFormatter::ORDINAL`:       http://php.net/manual/en/class.numberformatter.php#numberformatter.constants.ordinal
155.. _`NumberFormatter::DURATION`:      http://php.net/manual/en/class.numberformatter.php#numberformatter.constants.duration
156.. _`NumberFormatter::TYPE_DEFAULT`:  http://php.net/manual/en/class.numberformatter.php#numberformatter.constants.type-default
157.. _`NumberFormatter::TYPE_INT32`:    http://php.net/manual/en/class.numberformatter.php#numberformatter.constants.type-int32
158.. _`NumberFormatter::TYPE_INT64`:    http://php.net/manual/en/class.numberformatter.php#numberformatter.constants.type-int64
159.. _`NumberFormatter::TYPE_DOUBLE`:   http://php.net/manual/en/class.numberformatter.php#numberformatter.constants.type-double
160.. _`NumberFormatter::TYPE_CURRENCY`: http://php.net/manual/en/class.numberformatter.php#numberformatter.constants.type-currency
161