{"payload":{"allShortcutsEnabled":false,"fileTree":{"docs":{"items":[{"name":"admin_css.txt","path":"docs/admin_css.txt","contentType":"file"},{"name":"authentication.txt","path":"docs/authentication.txt","contentType":"file"},{"name":"cache.txt","path":"docs/cache.txt","contentType":"file"},{"name":"db-api.txt","path":"docs/db-api.txt","contentType":"file"},{"name":"design_philosophies.txt","path":"docs/design_philosophies.txt","contentType":"file"},{"name":"django-admin.txt","path":"docs/django-admin.txt","contentType":"file"},{"name":"faq.txt","path":"docs/faq.txt","contentType":"file"},{"name":"forms.txt","path":"docs/forms.txt","contentType":"file"},{"name":"generic_views.txt","path":"docs/generic_views.txt","contentType":"file"},{"name":"install.txt","path":"docs/install.txt","contentType":"file"},{"name":"legacy_databases.txt","path":"docs/legacy_databases.txt","contentType":"file"},{"name":"middleware.txt","path":"docs/middleware.txt","contentType":"file"},{"name":"model-api.txt","path":"docs/model-api.txt","contentType":"file"},{"name":"modpython.txt","path":"docs/modpython.txt","contentType":"file"},{"name":"outputting_pdf.txt","path":"docs/outputting_pdf.txt","contentType":"file"},{"name":"overview.txt","path":"docs/overview.txt","contentType":"file"},{"name":"request_response.txt","path":"docs/request_response.txt","contentType":"file"},{"name":"sessions.txt","path":"docs/sessions.txt","contentType":"file"},{"name":"settings.txt","path":"docs/settings.txt","contentType":"file"},{"name":"templates.txt","path":"docs/templates.txt","contentType":"file"},{"name":"templates_python.txt","path":"docs/templates_python.txt","contentType":"file"},{"name":"translation.txt","path":"docs/translation.txt","contentType":"file"},{"name":"tutorial01.txt","path":"docs/tutorial01.txt","contentType":"file"},{"name":"tutorial02.txt","path":"docs/tutorial02.txt","contentType":"file"},{"name":"tutorial03.txt","path":"docs/tutorial03.txt","contentType":"file"},{"name":"tutorial04.txt","path":"docs/tutorial04.txt","contentType":"file"},{"name":"url_dispatch.txt","path":"docs/url_dispatch.txt","contentType":"file"},{"name":"writing-apps-guide-outline.txt","path":"docs/writing-apps-guide-outline.txt","contentType":"file"}],"totalCount":28},"":{"items":[{"name":"django","path":"django","contentType":"directory"},{"name":"docs","path":"docs","contentType":"directory"},{"name":"tests","path":"tests","contentType":"directory"},{"name":"INSTALL","path":"INSTALL","contentType":"file"},{"name":"LICENSE","path":"LICENSE","contentType":"file"},{"name":"README","path":"README","contentType":"file"},{"name":"ez_setup.py","path":"ez_setup.py","contentType":"file"},{"name":"setup.py","path":"setup.py","contentType":"file"}],"totalCount":8}},"fileTreeProcessingTime":12.018024,"foldersToFetch":[],"repo":{"id":4164482,"defaultBranch":"main","name":"django","ownerLogin":"django","currentUserCanPush":false,"isFork":false,"isEmpty":false,"createdAt":"2012-04-28T02:47:18.000Z","ownerAvatar":"https://avatars.githubusercontent.com/u/27804?v=4","public":true,"private":false,"isOrgOwned":true},"symbolsExpanded":false,"treeExpanded":true,"refInfo":{"name":"6e7620baf0ca3dc5101f28ffc7eb66d1faa6960b","listCacheKey":"v0:1709542684.0","canEdit":false,"refType":"tree","currentOid":"6e7620baf0ca3dc5101f28ffc7eb66d1faa6960b"},"path":"docs/translation.txt","currentUser":null,"blob":{"rawLines":["====================","Internationalization","====================","","Django has full support for internationalization of text in code and templates.","Here's an overview of how translation works in Django.","",".. admonition:: Behind the scenes",""," Django's translation machinery uses the standard ``gettext`` module that"," comes with Python.","","Overview","========","","The goal of internationalization is to allow a single Web application to offer","its content and functionality in multiple languages.","","You, the Django developer, can accomplish this goal by adding a minimal amount","of hooks to your Python code and templates. These hooks are called","**translation strings**. 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.\"","","Django takes care of using these hooks to translate Web apps, on the fly,","according to users' language preferences.","","Essentially, Django does two things:",""," * It lets developers and template authors specify which parts of their apps"," should be translatable."," * It uses these hooks to translate Web apps for particular users according"," to their language preferences.","","How to internationalize your app: in three steps","------------------------------------------------",""," 1. Embed translation strings in your Python code and templates."," 2. Get translations for those strings, in whichever languages you want to"," support."," 2. Activate the locale middleware in your Django settings.","","How to specify translation strings","==================================","","Translation strings specify \"This text should be translated.\" These strings can","appear in your Python code and templates. It's your responsibility to mark","translatable strings; the system can only translate strings it knows about.","","In Python code","--------------","","Standard translation","~~~~~~~~~~~~~~~~~~~~","","Specify a translation string by using the function ``_()``. (Yes, the name of","the function is the \"underscore\" character.) This function is available","globally in any Python module; you don't have to import it.","","In this example, the text ``\"Welcome to my site.\"`` is marked as a translation","string::",""," def my_view(request):"," output = _(\"Welcome to my site.\")"," return HttpResponse(output)","","The function ``django.utils.translation.gettext()`` is identical to ``_()``.","This example is identical to the previous one::",""," 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 strings you pass to ``_()`` or ``gettext()`` can take placeholders,","specified with Python's standard named-string interpolation syntax. Example::",""," def my_view(request, n):"," output = _('%(name)s is my name.') % {'name': n}"," return HttpResponse(output)","","This technique lets language-specific translations reorder the placeholder","text. For example, an English translation may be ``\"Adrian is my name.\"``,","while a Spanish translation may be ``\"Me llamo Adrian.\"`` -- with the","placeholder (the name) placed after the translated text instead of before it.","","For this reason, you should use named-string interpolation (e.g., ``%(name)s``)","instead of positional interpolation (e.g., ``%s`` or ``%d``). If you used","positional interpolation, translations wouldn't be able to reorder placeholder","text.","","Marking strings as no-op","~~~~~~~~~~~~~~~~~~~~~~~~","","Use the function ``django.utils.translation.gettext_noop()`` to mark a string","as a translate string without translating it. The string is later translated","from a variable.","","Use this if you have constant strings that should be stored in the source","language because they are exchanged over systems or users -- such as strings in","a database -- but should be translated at the last possible point in time, such","as when the string is presented to the user.","","Lazy translation","~~~~~~~~~~~~~~~~","","Use the function ``django.utils.translation.gettext_lazy()`` to translate","strings lazily -- when the value is accessed rather than when the","``gettext_lazy()`` function is called.","","For example, to translate a model's ``help_text``, do the following::",""," from django.utils.translation import gettext_lazy",""," class MyThing(meta.Model):"," name = meta.CharField(help_text=gettext_lazy('This is the help text'))","","In this example, ``gettext_lazy()`` stores a lazy reference to the string --","not the actual translation. The translation itself will be done when the string","is used in a string context, such as template rendering on the Django admin site.","","If you don't like the verbose name ``gettext_lazy``, you can just alias it as","``_``, like so::",""," from django.utils.translation import gettext_lazy as _",""," class MyThing(meta.Model):"," name = meta.CharField(help_text=_('This is the help text'))","","Always use lazy translations in Django models. And it's a good idea to add","translations for the field names and table names, too. This means writing","explicit ``verbose_name`` and ``verbose_name_plural`` options in the ``META``","class, though::",""," from django.utils.translation import gettext_lazy as _",""," class MyThing(meta.Model):"," name = meta.CharField(_('name'), help_text=_('This is the help text'))"," class META:"," verbose_name = _('my thing')"," verbose_name_plural = _('mythings')","","Pluralization","~~~~~~~~~~~~~","","Use the function ``django.utils.translation.ngettext()`` to specify pluralized","messages. Example::",""," from django.utils.translation import ngettext"," def hello_world(request, count):"," page = ngettext('there is %(count)d object', 'there are %(count)d objects', count) % {"," 'count': count,"," }"," return HttpResponse(page)","","``ngettext`` takes three arguments: the singular translation string, the plural","translation string and the number of objects (which is passed to the","translation languages as the ``count`` variable).","","In template code","----------------","","Using translations in Django templates uses two template tags and a slightly","different syntax than in Python code. To give your template access to these","tags, put ``{% load i18n %}`` toward the top of your template.","","The ``{% trans %}`` template tag translates a constant string or a variable","content::","","