.. _locale:

Locales
=======

Mimesis supports multiple locales. This means that you can generate
data in different languages and for different countries.

The default locale for all providers is English (United States) (``Locale.EN``).

You have to import the :class:`~mimesis.enums.Locale` object first, like this:

.. code-block:: python

    from mimesis.locales import Locale

Now you can specify a locale when creating providers, and they will return data that
is appropriate for the language or country associated with that locale:

.. code-block:: python

    from mimesis import Address
    from mimesis.locales import Locale

    de = Address(locale=Locale.DE)
    ru = Address(locale=Locale.RU)

    de.region()
    # Output: 'Brandenburg'

    ru.federal_subject()
    # Output: 'Алтайский край'

    de.address()
    # Output: 'Mainzer Landstraße 912'

    ru.address()
    # Output: 'ул. Пехотная 125'

See the table below for more details.

Overriding locale
-----------------

Sometimes you need only some data from another locale, and creating a new instance
for such cases is not ideal, so it's better to temporarily override the current locale for the provider's instance:

.. code-block:: python

    from mimesis import Person
    from mimesis.locales import Locale

    person = Person(locale=Locale.EN)
    person.full_name()
    # Output: 'Ozie Melton'

    with person.override_locale(Locale.RU):
        person.full_name()

    # Output: 'Симона Богданова'

    person.full_name()
    # Output: 'Waldo Foster'

You can also use it with :class:`~mimesis.Generic()`:

.. code-block:: python

    from mimesis import Generic
    from mimesis.locales import Locale

    generic = Generic(locale=Locale.EN)
    generic.text.word()
    # Output: 'anyone'

    with generic.text.override_locale(Locale.FR):
        generic.text.word()

    # Output: 'mieux'

    generic.text.word()
    # Output: 'responsibilities'

Supported locales
-----------------

Mimesis currently includes support for 47 different locales (see :class:`~mimesis.enums.Locale` for more details).

The table below lists all supported locales and their associated
countries.

=======  =======  ====================  ====================  ====================
Country   Code    Associated attribute  Name                  Native Name
=======  =======  ====================  ====================  ====================
   🇦🇪    `ar-ae`  **Locale.AR_AE**      Arabic U.A.E          العربية
   🇩🇿    `ar-dz`  **Locale.AR_DZ**      Arabic Algeria        العربية
   🇪🇬    `ar-eg`  **Locale.AR_EG**      Arabic Egypt          العربية
   🇯🇴    `ar-jo`  **Locale.AR_JO**      Arabic Jordan         العربية
   🇰🇼    `ar-kw`  **Locale.AR_KW**      Arabic Kuwait         العربية
   🇲🇦    `ar-ma`  **Locale.AR_MA**      Arabic Morocco        العربية
   🇴🇲    `ar-om`  **Locale.AR_OM**      Arabic Oman           العربية
   🇶🇦    `ar-qa`  **Locale.AR_QA**      Arabic Qatar          العربية
   🇸🇦    `ar-sa`  **Locale.AR_SA**      Arabic Saudi Arabia   العربية
   🇸🇾    `ar-sy`  **Locale.AR_SY**      Arabic Syria          العربية
   🇹🇳    `ar-tn`  **Locale.AR_TN**      Arabic Tunisia        العربية
   🇾🇪    `ar-ye`  **Locale.AR_YE**      Arabic Yemen          العربية
   🇨🇿    `cs`     **Locale.CS**         Czech                 Česky
   🇩🇰    `da`     **Locale.DA**         Danish                Dansk
   🇩🇪    `de`     **Locale.DE**         German                Deutsch
   🇦🇹    `de-at`  **Locale.DE_AT**      Austrian German       Deutsch
   🇨🇭    `de-ch`  **Locale.DE_CH**      Swiss German          Deutsch
   🇬🇷    `el`     **Locale.EL**         Greek                 Ελληνικά
   🇺🇸    `en`     **Locale.EN**         English               English
   🇦🇺    `en-au`  **Locale.EN_AU**      Australian English    English
   🇨🇦    `en-ca`  **Locale.EN_CA**      Canadian English      English
   🇬🇧    `en-gb`  **Locale.EN_GB**      British English       English
   🇪🇸    `es`     **Locale.ES**         Spanish               Español
   🇲🇽    `es-mx`  **Locale.ES_MX**      Mexican Spanish       Español
   🇪🇪    `et`     **Locale.ET**         Estonian              Eesti
   🇮🇷    `fa`     **Locale.FA**         Farsi                 فارسی
   🇫🇮    `fi`     **Locale.FI**         Finnish               Suomi
   🇫🇷    `fr`     **Locale.FR**         French                Français
   🇭🇷    `hr`     **Locale.HR**         Croatian              Hrvatski
   🇭🇺    `hu`     **Locale.HU**         Hungarian             Magyar
   🇮🇸    `is`     **Locale.IS**         Icelandic             Íslenska
   🇮🇹    `it`     **Locale.IT**         Italian               Italiano
   🇯🇵    `ja`     **Locale.JA**         Japanese              日本語
   🇰🇿    `kk`     **Locale.KK**         Kazakh                Қазақша
   🇰🇷    `ko`     **Locale.KO**         Korean                한국어
   🇳🇱    `nl`     **Locale.NL**         Dutch                 Nederlands
   🇧🇪    `nl-be`  **Locale.NL_BE**      Belgian Dutch         Nederlands
   🇳🇴    `no`     **Locale.NO**         Norwegian             Norsk
   🇵🇱    `pl`     **Locale.PL**         Polish                Polski
   🇵🇹    `pt`     **Locale.PT**         Portuguese            Português
   🇧🇷    `pt-br`  **Locale.PT_BR**      Brazilian Portuguese  Português Brasileiro
   🇷🇺    `ru`     **Locale.RU**         Russian               Русский
   🇸🇰    `sk`     **Locale.SK**         Slovak                Slovensky
   🇸🇪    `sv`     **Locale.SV**         Swedish               Svenska
   🇹🇷    `tr`     **Locale.TR**         Turkish               Türkçe
   🇺🇦    `uk`     **Locale.UK**         Ukrainian             Українська
   🇨🇳    `zh`     **Locale.ZH**         Chinese               汉语
=======  =======  ====================  ====================  ====================
