<commit_before>===========
Translation
===========

.. currentmodule:: django.utils.translation

Overview
========

In order to make a Django project translatable, you have to add a minimal
number of hooks to your Python code and templates. These hooks are called
:term:`translation strings <translation string>`. They tell Django: "This text
should be translated into the end user's language, if a translation for this
text is available in that language." It's your responsibility to mark
translatable strings; the system can only translate strings it knows about.

Django then provides utilities to extract the translation strings into a
:term:`message file`. This file is a convenient way for translators to provide
the equivalent of the translation strings in the target language. Once the
translators have filled in the message file, it must be compiled. This process
relies on the GNU gettext toolset.

Once this is done, Django takes care of translating Web apps on the fly in each
available language, according to users' language preferences.

Django's internationalization hooks are on by default, and that means there's a
bit of i18n-related overhead in certain places of the framework. If you don't
use internationalization, you should take the two seconds to set
:setting:`USE_I18N = False <USE_I18N>` in your settings file. Then Django will
make some optimizations so as not to load the internationalization machinery.

.. note::

    There is also an independent but related :setting:`USE_L10N` setting that
    controls if Django should implement format localization. See
    :doc:`/topics/i18n/formatting` for more details.

.. note::

    Make sure you've activated translation for your project (the fastest way is
    to check if :setting:`MIDDLEWARE` includes
    :mod:`django.middleware.locale.LocaleMiddleware`). If you haven't yet,
    see :ref:`how-django-discovers-language-preference`.

Internationalization: in Python code
====================================

Standard translation
--------------------

Specify a translation string by using the function
:func:`~django.utils.translation.gettext`. It's convention to import this
as a shorter alias, ``_``, to save typing.

.. note::
    Python's standard library ``gettext`` module installs ``_()`` into the
    global namespace, as an alias for ``gettext()``. In Django, we have chosen
    not to follow this practice, for a couple of reasons:

    #. Sometimes, you should use :func:`~django.utils.translation.gettext_lazy`
       as the default translation method for a particular file. Without ``_()``
       in the global namespace, the developer has to think about which is the
       most appropriate translation function.

    #. The underscore character (``_``) is used to represent "the previous
       result" in Python's interactive shell and doctest tests. Installing a
       global ``_()`` function causes interference. Explicitly importing
       ``gettext()`` as ``_()`` avoids this problem.

.. admonition:: What functions may be aliased as ``_``?

    Because of how ``xgettext`` (used by :djadmin:`makemessages`) works, only
    functions that take a single string argument can be imported as ``_``:

    * :func:`~django.utils.translation.gettext`
    * :func:`~django.utils.translation.gettext_lazy`

In this example, the text ``"Welcome to my site."`` is marked as a translation
string::

    from django.http import HttpResponse
    from django.utils.translation import gettext as _

    def my_view(request):
        output = _("Welcome to my site.")
        return HttpResponse(output)

You could code this without using the alias. This example is identical to the
previous one::

    from django.http import HttpResponse
    from django.utils.translation import gettext

    def my_view(request):
        output = gettext("Welcome to my site.")
        return HttpResponse(output)

Translation works on computed values. This example is identical to the previous
two::

    def my_view(request):
        words = ['Welcome', 'to', 'my', 'site.']
        output = _(' '.join(words))
        return HttpResponse(output)

Translation works on variables. Again, here's an identical example::

    def my_view(request):
        sentence = 'Welcome to my site.'
        output = _(sentence)
        return HttpResponse(output)

(The caveat with using variables or computed values, as in the previous two
examples, is that Django's translation-string-detecting utility,
:djadmin:`django-admin makemessages <makemessages>`, won't be able to find
these strings. More on :djadmin:`makemessages` later.)

The strings you pass to ``_()`` or ``gettext()`` can take placeholders,
specified with Python's standard named-string interpolation syntax. Example::

    def my_view(request, m, d):
        output = _('Today is %(month)s %(day)s.') % {'month': m, 'day': d}
        return HttpResponse(output)

This technique lets language-specific translations reorder the placeholder
text. For example, an English translation may be ``"Today is November 26."``,
while a Spanish translation may be ``"Hoy es 26 de Noviembre."`` -- with the
month and the day placeholders swapped.

For this reason, you should use named-string interpolation (e.g., ``%(day)s``)
instead of positional interpolation (e.g., ``%s`` or ``%d``) whenever you
have more than a single parameter. If you used positional interpolation,
translations wouldn't be able to reorder placeholder text.
<commit_msg>Fixed typo in docs/topics/i18n/translation.txt.<commit_after>===========
Translation
===========

.. currentmodule:: django.utils.translation

Overview
========

In order to make a Django project translatable, you have to add a minimal
number of hooks to your Python code and templates. These hooks are called
:term:`translation strings <translation string>`. They tell Django: "This text
should be translated into the end user's language, if a translation for this
text is available in that language." It's your responsibility to mark
translatable strings; the system can only translate strings it knows about.

Django then provides utilities to extract the translation strings into a
:term:`message file`. This file is a convenient way for translators to provide
the equivalent of the translation strings in the target language. Once the
translators have filled in the message file, it must be compiled. This process
relies on the GNU gettext toolset.

Once this is done, Django takes care of translating Web apps on the fly in each
available language, according to users' language preferences.

Django's internationalization hooks are on by default, and that means there's a
bit of i18n-related overhead in certain places of the framework. If you don't
use internationalization, you should take the two seconds to set
:setting:`USE_I18N = False <USE_I18N>` in your settings file. Then Django will
make some optimizations so as not to load the internationalization machinery.

.. note::

    There is also an independent but related :setting:`USE_L10N` setting that
    controls if Django should implement format localization. See
    :doc:`/topics/i18n/formatting` for more details.

.. note::

    Make sure you've activated translation for your project (the fastest way is
    to check if :setting:`MIDDLEWARE` includes
    :mod:`django.middleware.locale.LocaleMiddleware`). If you haven't yet,
    see :ref:`how-django-discovers-language-preference`.

Internationalization: in Python code
====================================

Standard translation
--------------------

Specify a translation string by using the function
:func:`~django.utils.translation.gettext`. It's convention to import this
as a shorter alias, ``_``, to save typing.

.. note::
    Python's standard library ``gettext`` module installs ``_()`` into the
    global namespace, as an alias for ``gettext()``. In Django, we have chosen
    not to follow this practice, for a couple of reasons:

    #. Sometimes, you should use :func:`~django.utils.translation.gettext_lazy`
       as the default translation method for a particular file. Without ``_()``
       in the global namespace, the developer has to think about which is the
       most appropriate translation function.

    #. The underscore character (``_``) is used to represent "the previous
       result" in Python's interactive shell and doctest tests. Installing a
       global ``_()`` function causes interference. Explicitly importing
       ``gettext()`` as ``_()`` avoids this problem.

.. admonition:: What functions may be aliased as ``_``?

    Because of how ``xgettext`` (used by :djadmin:`makemessages`) works, only
    functions that take a single string argument can be imported as ``_``:

    * :func:`~django.utils.translation.gettext`
    * :func:`~django.utils.translation.gettext_lazy`

In this example, the text ``"Welcome to my site."`` is marked as a translation
string::

    from django.http import HttpResponse
    from django.utils.translation import gettext as _

    def my_view(request):
        output = _("Welcome to my site.")
        return HttpResponse(output)

You could code this without using the alias. This example is identical to the
previous one::

    from django.http import HttpResponse
    from django.utils.translation import gettext

    def my_view(request):
        output = gettext("Welcome to my site.")
        return HttpResponse(output)

Translation works on computed values. This example is identical to the previous
two::

    def my_view(request):
        words = ['Welcome', 'to', 'my', 'site.']
        output = _(' '.join(words))
        return HttpResponse(output)

Translation works on variables. Again, here's an identical example::

    def my_view(request):
        sentence = 'Welcome to my site.'
        output = _(sentence)
        return HttpResponse(output)

(The caveat with using variables or computed values, as in the previous two
examples, is that Django's translation-string-detecting utility,
:djadmin:`django-admin makemessages <makemessages>`, won't be able to find
these strings. More on :djadmin:`makemessages` later.)

The strings you pass to ``_()`` or ``gettext()`` can take placeholders,
specified with Python's standard named-string interpolation syntax. Example::

    def my_view(request, m, d):
        output = _('Today is %(month)s %(day)s.') % {'month': m, 'day': d}
        return HttpResponse(output)

This technique lets language-specific translations reorder the placeholder
text. For example, an English translation may be ``"Today is November 26."``,
while a Spanish translation may be ``"Hoy es 26 de noviembre."`` -- with the
month and the day placeholders swapped.

For this reason, you should use named-string interpolation (e.g., ``%(day)s``)
instead of positional interpolation (e.g., ``%s`` or ``%d``) whenever you
have more than a single parameter. If you used positional interpolation,
translations wouldn't be able to reorder placeholder text.

{'fraction_non_alphanumeric': 0.09926940639269406, 'fraction_numerical': 0.0027397260273972603, 'mean_word_length': 4.030316949931098, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1188401', 'n_tokens_mistral': 2901, 'n_tokens_neox': 2732, 'n_words': 1323}