symfony
diff --git a/‎reference/constraints/Locale.rst
Lines changed: 28 additions & 8 deletions b/‎reference/constraints/Locale.rst
Lines changed: 28 additions & 8 deletions
@@ -3,16 +3,17 @@ Locale
 
 Validates that a value is a valid locale.
 
-The "value" for each locale is either the two letter `ISO 639-1`_ *language*
-code (e.g. ``fr``), or the language code followed by an underscore (``_``),
-then the `ISO 3166-1 alpha-2`_ *country* code (e.g. ``fr_FR`` for
-French/France).
+The "value" for each locale is any of `ICU format locale IDs`. By instance the two
+letter `ISO 639-1`_ *language* code (e.g. ``fr``), or the language code followed
+by an underscore (``_``), then the `ISO 3166-1 alpha-2`_ *country* code (e.g. ``fr_FR``
+for French/France).
 
 +----------------+------------------------------------------------------------------------+
 | Applies to     | :ref:`property or method <validation-property-target>`                 |
 +----------------+------------------------------------------------------------------------+
 | Options        | - `message`_                                                           |
 |                | - `payload`_                                                           |
+|                | - `canonicalize`_                                                      |
 +----------------+------------------------------------------------------------------------+
 | Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Locale`            |
 +----------------+------------------------------------------------------------------------+
@@ -34,7 +35,9 @@ Basic Usage
         class User
         {
             /**
-             * @Assert\Locale()
+             * @Assert\Locale(
+             *     canonicalize = true
+             * )
              */
              protected $locale;
         }
@@ -45,7 +48,8 @@ Basic Usage
         App\Entity\User:
             properties:
                 locale:
-                    - Locale: ~
+                    - Locale:
+                        canonicalize: true
 
     .. code-block:: xml
 
@@ -57,7 +61,9 @@ Basic Usage
 
             <class name="App\Entity\User">
                 <property name="locale">
-                    <constraint name="Locale" />
+                    <constraint name="Locale">
+                        <option name="canonicalize">true</option>
+                    </constraint>
                 </property>
             </class>
         </constraint-mapping>
@@ -74,7 +80,7 @@ Basic Usage
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
-                $metadata->addPropertyConstraint('locale', new Assert\Locale());
+                $metadata->addPropertyConstraint('locale', new Assert\Locale(array('canonicalize' => true)));
             }
         }
 
@@ -90,5 +96,19 @@ This message is shown if the string is not a valid locale.
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
+canonicalize
+~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+.. versionadded:: 4.1
+    Using this option with value ``false`` was deprecated in Symfony 4.1 and it
+    will throw an exception in Symfony 5.0, use `true` instead.
+
+If true, the :phpmethod:`Locale::canonicalize` method will be applied before checking
+the validity of the given locale (e.g. ``FR-fr.utf8`` is transformed into ``fr_FR``
+).
+
 .. _`ISO 639-1`: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
 .. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes
+.. _`ICU format locale IDs`: http://userguide.icu-project.org/locale#TOC-Canonicalization