Terjemahan standar¶

Specify a translation string by using the function gettext(). It's convention to import this as a shorter alias, _, to save typing.

Di contoh ini, teks "Welcome to my site." ditandai sebagai deretan karakter terjemahan:

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

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

Obviously, 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)

Terjemahan bekerja pada variabel. Kembali, ini adalah contoh yang mirip:

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, django-admin makemessages, won't be able to find these strings. More on 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.

Since string extraction is done by the xgettext command, only syntaxes supported by gettext are supported by Django. Python f-strings and JavaScript template strings are not yet supported by xgettext.

Komentar untuk penterjemah¶

If you would like to give translators hints about a translatable string, you can add a comment prefixed with the Translators keyword on the line preceding the string, e.g.:

def my_view(request):
    # Translators: This message appears on the home page only
    output = gettext("Welcome to my site.")

The comment will then appear in the resulting .po file associated with the translatable construct located below it and should also be displayed by most translation tools.

#. Translators: This message appears on the home page only
# path/to/python/file.py:123
msgid "Welcome to my site."
msgstr ""

This also works in templates. See Komentar untuk penterjemah dalam cetakan for more details.

Marking strings as no-op¶

Use the function django.utils.translation.gettext_noop() to mark a string as a translation 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.

Pluralization¶

Use the function django.utils.translation.ngettext() to specify pluralized messages.

ngettext() takes three arguments: the singular translation string, the plural translation string and the number of objects.

This function is useful when you need your Django application to be localizable to languages where the number and complexity of plural forms is greater than the two forms used in English ('object' for the singular and 'objects' for all the cases where count is different from one, irrespective of its value.)

Sebagai contoh:

from django.http import HttpResponse
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)

In this example the number of objects is passed to the translation languages as the count variable.

Note that pluralization is complicated and works differently in each language. Comparing count to 1 isn't always the correct rule. This code looks sophisticated, but will produce incorrect results for some languages:

from django.utils.translation import ngettext
from myapp.models import Report

count = Report.objects.count()
if count == 1:
    name = Report._meta.verbose_name
else:
    name = Report._meta.verbose_name_plural

text = ngettext(
    'There is %(count)d %(name)s available.',
    'There are %(count)d %(name)s available.',
    count
) % {
    'count': count,
    'name': name
}

Don't try to implement your own singular-or-plural logic, it won't be correct. In a case like this, consider something like the following:

text = ngettext(
    'There is %(count)d %(name)s object available.',
    'There are %(count)d %(name)s objects available.',
    count
) % {
    'count': count,
    'name': Report._meta.verbose_name,
}

text = ngettext(
    'There is %(count)d %(name)s available.',
    'There are %(count)d %(plural_name)s available.',
    count
) % {
    'count': Report.objects.count(),
    'name': Report._meta.verbose_name,
    'plural_name': Report._meta.verbose_name_plural
}

a format specification for argument 'name', as in 'msgstr[0]', doesn't exist in 'msgid'

Contextual markers¶

Sometimes words have several meanings, such as "May" in English, which refers to a month name and to a verb. To enable translators to translate these words correctly in different contexts, you can use the django.utils.translation.pgettext() function, or the django.utils.translation.npgettext() function if the string needs pluralization. Both take a context string as the first variable.

In the resulting .po file, the string will then appear as often as there are different contextual markers for the same string (the context will appear on the msgctxt line), allowing the translator to give a different translation for each of them.

Sebagai contoh:

from django.utils.translation import pgettext

month = pgettext("month name", "May")

atau:

from django.db import models
from django.utils.translation import pgettext_lazy

class MyThing(models.Model):
    name = models.CharField(help_text=pgettext_lazy(
        'help text for MyThing model', 'This is the help text'))

akan muncul di berkas .po sebagai:

msgctxt "month name"
msgid "May"
msgstr ""

Contextual markers are also supported by the trans and blocktrans template tags.

Terjemahan lazy¶

Use the lazy versions of translation functions in django.utils.translation (easily recognizable by the lazy suffix in their names) to translate strings lazily -- when the value is accessed rather than when they're called.

These functions store 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 in template rendering.

This is essential when calls to these functions are located in code paths that are executed at module load time.

This is something that can easily happen when defining models, forms and model forms, because Django implements these such that their fields are actually class-level attributes. For that reason, make sure to use lazy translations in the following cases:

from django.db import models
from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    name = models.CharField(help_text=_('This is the help text'))

class MyThing(models.Model):
    kind = models.ForeignKey(
        ThingKind,
        on_delete=models.CASCADE,
        related_name='kinds',
        verbose_name=_('kind'),
    )

from django.db import models
from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    name = models.CharField(_('name'), help_text=_('This is the help text'))

    class Meta:
        verbose_name = _('my thing')
        verbose_name_plural = _('my things')

from django.db import models
from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    kind = models.ForeignKey(
        ThingKind,
        on_delete=models.CASCADE,
        related_name='kinds',
        verbose_name=_('kind'),
    )

    def is_mouse(self):
        return self.kind.type == MOUSE_TYPE
    is_mouse.short_description = _('Is it a mouse?')

Working with lazy translation objects¶

The result of a gettext_lazy() call can be used wherever you would use a string (a str object) in other Django code, but it may not work with arbitrary Python code. For example, the following won't work because the requests library doesn't handle gettext_lazy objects:

body = gettext_lazy("I \u2764 Django")  # (unicode :heart:)
requests.post('https://example.com/send', data={'body': body})

You can avoid such problems by casting gettext_lazy() objects to text strings before passing them to non-Django code:

requests.post('https://example.com/send', data={'body': str(body)})

If you don't like the long gettext_lazy name, you can just alias it as _ (underscore), like so:

from django.db import models
from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    name = models.CharField(help_text=_('This is the help text'))

Using gettext_lazy() and ngettext_lazy() to mark strings in models and utility functions is a common operation. When you're working with these objects elsewhere in your code, you should ensure that you don't accidentally convert them to strings, because they should be converted as late as possible (so that the correct locale is in effect). This necessitates the use of the helper function described next.

from django import forms
from django.utils.translation import ngettext_lazy

class MyForm(forms.Form):
    error_message = ngettext_lazy("You only provided %(num)d argument",
        "You only provided %(num)d arguments", 'num')

    def clean(self):
        # ...
        if error:
            raise forms.ValidationError(self.error_message % {'num': number})

class MyForm(forms.Form):
    error_message = ngettext_lazy(
        "You provided %d argument",
        "You provided %d arguments",
    )

    def clean(self):
        # ...
        if error:
            raise forms.ValidationError(self.error_message % number)

from django.utils.text import format_lazy
from django.utils.translation import gettext_lazy
...
name = gettext_lazy('John Lennon')
instrument = gettext_lazy('guitar')
result = format_lazy('{name}: {instrument}', name=name, instrument=instrument)

from django.utils.functional import lazy
from django.utils.safestring import mark_safe
from django.utils.translation import gettext_lazy as _

mark_safe_lazy = lazy(mark_safe, str)

lazy_string = mark_safe_lazy(_("<p>My <strong>string!</strong></p>"))

Localized names of languages¶

get_language_info()[sumber]¶

Fungsi get_language_info() menyediakan informasi rinci tentang bahasa:

>>> from django.utils.translation import activate, get_language_info
>>> activate('fr')
>>> li = get_language_info('de')
>>> print(li['name'], li['name_local'], li['name_translated'], li['bidi'])
German Deutsch Allemand False

The name, name_local, and name_translated attributes of the dictionary contain the name of the language in English, in the language itself, and in your current active language respectively. The bidi attribute is True only for bi-directional languages.

The source of the language information is the django.conf.locale module. Similar access to this information is available for template code. See below.

Etiket cetakan trans¶

The {% trans %} template tag translates either a constant string (enclosed in single or double quotes) or variable content:

<title>{% trans "This is the title." %}</title>
<title>{% trans myvar %}</title>

If the noop option is present, variable lookup still takes place but the translation is skipped. This is useful when "stubbing out" content that will require translation in the future:

<title>{% trans "myvar" noop %}</title>

Internally, inline translations use an gettext() call.

In case a template var (myvar above) is passed to the tag, the tag will first resolve such variable to a string at run-time and then look up that string in the message catalogs.

It's not possible to mix a template variable inside a string within {% trans %}. If your translations require strings with variables (placeholders), use {% blocktrans %} instead.

If you'd like to retrieve a translated string without displaying it, you can use the following syntax:

{% trans "This is the title" as the_title %}

<title>{{ the_title }}</title>
<meta name="description" content="{{ the_title }}">

In practice you'll use this to get a string you can use in multiple places in a template or so you can use the output as an argument for other template tags or filters:

{% trans "starting point" as start %}
{% trans "end point" as end %}
{% trans "La Grande Boucle" as race %}

<h1>
  <a href="/" title="{% blocktrans %}Back to '{{ race }}' homepage{% endblocktrans %}">{{ race }}</a>
</h1>
<p>
{% for stage in tour_stages %}
    {% cycle start end %}: {{ stage }}{% if forloop.counter|divisibleby:2 %}<br />{% else %}, {% endif %}
{% endfor %}
</p>

{% trans %} also supports contextual markers using the context keyword:

{% trans "May" context "month name" %}

Etiket cetakan blocktrans¶

Contrarily to the trans tag, the blocktrans tag allows you to mark complex sentences consisting of literals and variable content for translation by making use of placeholders:

{% blocktrans %}This string will have {{ value }} inside.{% endblocktrans %}

To translate a template expression -- say, accessing object attributes or using template filters -- you need to bind the expression to a local variable for use within the translation block. Examples:

{% blocktrans with amount=article.price %}
That will cost $ {{ amount }}.
{% endblocktrans %}

{% blocktrans with myvar=value|filter %}
This will have {{ myvar }} inside.
{% endblocktrans %}

You can use multiple expressions inside a single blocktrans tag:

{% blocktrans with book_t=book|title author_t=author|title %}
This is {{ book_t }} by {{ author_t }}
{% endblocktrans %}

Other block tags (for example {% for %} or {% if %}) are not allowed inside a blocktrans tag.

If resolving one of the block arguments fails, blocktrans will fall back to the default language by deactivating the currently active language temporarily with the deactivate_all() function.

This tag also provides for pluralization. To use it:

• Designate and bind a counter value with the name count. This value will be the one used to select the right plural form.
• Specify both the singular and plural forms separating them with the {% plural %} tag within the {% blocktrans %} and {% endblocktrans %} tags.

Sebuah contoh:

{% blocktrans count counter=list|length %}
There is only one {{ name }} object.
{% plural %}
There are {{ counter }} {{ name }} objects.
{% endblocktrans %}

A more complex example:

{% blocktrans with amount=article.price count years=i.length %}
That will cost $ {{ amount }} per year.
{% plural %}
That will cost $ {{ amount }} per {{ years }} years.
{% endblocktrans %}

When you use both the pluralization feature and bind values to local variables in addition to the counter value, keep in mind that the blocktrans construct is internally converted to an ngettext call. This means the same notes regarding ngettext variables apply.

Reverse URL lookups cannot be carried out within the blocktrans and should be retrieved (and stored) beforehand:

{% url 'path.to.view' arg arg2 as the_url %}
{% blocktrans %}
This is a URL: {{ the_url }}
{% endblocktrans %}

If you'd like to retrieve a translated string without displaying it, you can use the following syntax:

{% blocktrans asvar the_title %}The title is {{ title }}.{% endblocktrans %}
<title>{{ the_title }}</title>
<meta name="description" content="{{ the_title }}">

In practice you'll use this to get a string you can use in multiple places in a template or so you can use the output as an argument for other template tags or filters.

{% blocktrans %} also supports contextual markers using the context keyword:

{% blocktrans with name=user.username context "greeting" %}Hi {{ name }}{% endblocktrans %}

Dukungan {% blocktrans %} fitur lain adalah pilihan trimmed. Pilihan ini akan memindahkan karakter baris baru dari awal dan akhir dari isi dari etiket {% blocktrans %}, ganti setiap ruang kosong pada awal dan akhir dari sebuah baris dan menggabungkan semua baris kedalam satu menggunakan karakter ruang kosong untuk memisahkan mereka. Ini sangat berguna untuk melekukkan isi dari etiket {% blocktrans %} tanpa memiliki karakter lekukan terakhir di masukan yang sesuai di berkas PO, yang membuat pengolahan terjemahan lebih mudah.

Untuk contoh, etiket {% blocktrans %} berikut:

{% blocktrans trimmed %}
  First sentence.
  Second paragraph.
{% endblocktrans %}

will result in the entry "First sentence. Second paragraph." in the PO file, compared to "\n  First sentence.\n  Second sentence.\n", if the trimmed option had not been specified.

String literals passed to tags and filters¶

You can translate string literals passed as arguments to tags and filters by using the familiar _() syntax:

{% some_tag _("Page not found") value|yesno:_("yes,no") %}

In this case, both the tag and the filter will see the translated string, so they don't need to be aware of translations.

Komentar untuk penterjemah dalam cetakan¶

Just like with Python code, these notes for translators can be specified using comments, either with the comment tag:

{% comment %}Translators: View verb{% endcomment %}
{% trans "View" %}

{% comment %}Translators: Short intro blurb{% endcomment %}
<p>{% blocktrans %}A multiline translatable
literal.{% endblocktrans %}</p>

or with the {# ... #} one-line comment constructs:

{# Translators: Label of a button that triggers search #}
<button type="submit">{% trans "Go" %}</button>

{# Translators: This is a text of the base template #}
{% blocktrans %}Ambiguous translatable block of text{% endblocktrans %}

#. Translators: View verb
# path/to/template/file.html:10
msgid "View"
msgstr ""

#. Translators: Short intro blurb
# path/to/template/file.html:13
msgid ""
"A multiline translatable"
"literal."
msgstr ""

# ...

#. Translators: Label of a button that triggers search
# path/to/template/file.html:100
msgid "Go"
msgstr ""

#. Translators: This is a text of the base template
# path/to/template/file.html:103
msgid "Ambiguous translatable block of text"
msgstr ""

Mengganti bahasa dalam cetakan¶

Jika anda ingin memilih sebuah bahasa dalam sebuah cetakan, anda dapat menggunakan etiket cetakan language:

{% load i18n %}

{% get_current_language as LANGUAGE_CODE %}
<!-- Current language: {{ LANGUAGE_CODE }} -->
<p>{% trans "Welcome to our page" %}</p>

{% language 'en' %}
    {% get_current_language as LANGUAGE_CODE %}
    <!-- Current language: {{ LANGUAGE_CODE }} -->
    <p>{% trans "Welcome to our page" %}</p>
{% endlanguage %}

While the first occurrence of "Welcome to our page" uses the current language, the second will always be in English.

Etiket lain¶

Etiket ini juga membutuhkan sebuah {% memuat i18n %}.

{% get_language_info for LANGUAGE_CODE as lang %}
{% get_language_info for "pl" as lang %}

Language code: {{ lang.code }}<br />
Name of language: {{ lang.name_local }}<br />
Name in English: {{ lang.name }}<br />
Bi-directional: {{ lang.bidi }}
Name in the active language: {{ lang.name_translated }}

context = {'available_languages': ['en', 'es', 'fr']}
return render(request, 'mytemplate.html', context)

{% get_language_info_list for available_languages as langs %}
{% for lang in langs %} ... {% endfor %}

Tampilan JavaScriptCatalog¶

class JavaScriptCatalog[sumber]¶

A view that produces a JavaScript code library with functions that mimic the gettext interface, plus an array of translation strings.

Attributes

domain¶

Translation domain containing strings to add in the view output. Defaults to 'djangojs'.

packages¶

A list of application names among installed applications. Those apps should contain a locale directory. All those catalogs plus all catalogs found in LOCALE_PATHS (which are always included) are merged into one catalog. Defaults to None, which means that all available translations from all INSTALLED_APPS are provided in the JavaScript output.

Example with default values:

from django.views.i18n import JavaScriptCatalog

urlpatterns = [
    path('jsi18n/', JavaScriptCatalog.as_view(), name='javascript-catalog'),
]

Example with custom packages:

urlpatterns = [
    path('jsi18n/myapp/',
         JavaScriptCatalog.as_view(packages=['your.app.label']),
         name='javascript-catalog'),
]

If your root URLconf uses i18n_patterns(), JavaScriptCatalog must also be wrapped by i18n_patterns() for the catalog to be correctly generated.

Example with i18n_patterns():

from django.conf.urls.i18n import i18n_patterns

urlpatterns = i18n_patterns(
    path('jsi18n/', JavaScriptCatalog.as_view(), name='javascript-catalog'),
)

The precedence of translations is such that the packages appearing later in the packages argument have higher precedence than the ones appearing at the beginning. This is important in the case of clashing translations for the same literal.

If you use more than one JavaScriptCatalog view on a site and some of them define the same strings, the strings in the catalog that was loaded last take precedence.

Menggunakan katalog terjemahan JavaScript¶

Untuk menggunakan katalog, cukup tarik di tulisan dibangkitkan dinamis seperti ini:

<script type="text/javascript" src="{% url 'javascript-catalog' %}"></script>

This uses reverse URL lookup to find the URL of the JavaScript catalog view. When the catalog is loaded, your JavaScript code can use the following methods:

• gettext
• ngettext
• interpolate
• get_format
• gettext_noop
• pgettext
• npgettext
• pluralidx

document.write(gettext('this is to be translated'));

var object_count = 1 // or 0, or 2, or 3, ...
s = ngettext('literal for the singular case',
        'literal for the plural case', object_count);

document.write(get_format('DATE_FORMAT'));
// 'N j, Y'

document.write(gettext_noop('this will not be translated'));

document.write(pgettext('month name', 'May'));

document.write(npgettext('group', 'party', 1));
// party
document.write(npgettext('group', 'party', 2));
// parties

document.write(pluralidx(0));
// true
document.write(pluralidx(1));
// false
document.write(pluralidx(2));
// true

Tampilan JSONCatalog¶

class JSONCatalog[sumber]¶

Untuk menggunakan pustaka sisi-klien lain untuk menangani terjemahan, anda mungkin ingin mengambil keuntungan dari tampilan JSONCatalog. Itu mirip pada JavaScriptCatalog tetapi mengembalikan sebuah tanggapan JSON.

Lihat dokumentasi untuk JavaScriptCatalog untuk belajar tentang kemungkinan nilai-nilai dan penggunaan dari atribut-atribut domain dan packages.

Bentuk tanggapan sebagai berikut:

{
    "catalog": {
        # Translations catalog
    },
    "formats": {
        # Language formats for date, time, etc.
    },
    "plural": "..."  # Expression for plural forms, or null.
}

Catatan pada penampilan¶

Tampilan beragam i18n JavaScript/JSON membangkitkan katalog dari berkas-berkas .mo pada setiap permintaan. Sejak itu mengeluarkan sebuah ketetapan, setidaknya untuk versi diberikan dari sebuah situs, itu adalah calon bagus untuk caching.

Caching sisi-peladen akan mengurangi beban CPU. Itu sangat mudah diterapkan dengan penghias cache_page(). Untuk memicu ketidakabsahan cache ketika terjemahan anda berubah, sediakan awalan kunci versi-berdiri-sendiri, seperti ditunjukkan dalam contoh dibawah atau tampilan peta pada URL versi-berdiri-sendiri:

from django.views.decorators.cache import cache_page
from django.views.i18n import JavaScriptCatalog

# The value returned by get_version() must change when translations change.
urlpatterns = [
    path('jsi18n/',
         cache_page(86400, key_prefix='js18n-%s' % get_version())(JavaScriptCatalog.as_view()),
         name='javascript-catalog'),
]

Caching sisi-klien akan menyimpan lebar pita dan membuat situs anda dimuat lebih cepat. Jika anda sedang menggunakan ETag (ConditionalGetMiddleware), anda siap dicakupi. Sebaliknya, anda dapat memberlakukan conditional decorators 1. Dalam contoh berikut, cache tidak berlaku ketika anda memulai kembali peladen aplikasi anda:

from django.utils import timezone
from django.views.decorators.http import last_modified
from django.views.i18n import JavaScriptCatalog

last_modified_date = timezone.now()

urlpatterns = [
    path('jsi18n/',
         last_modified(lambda req, **kw: last_modified_date)(JavaScriptCatalog.as_view()),
         name='javascript-catalog'),
]

Anda dapat bahkan pra-membangkitkan katalog JavaScript sebagai bagian dari prosedur pegembangan anda dan melayani itu sebagai berkas tetap. Teknik radikal ini adalah diterapkan dalam django-statici18n.

Awalan bahasa dalam pola URL¶

i18n_patterns(*urls, prefix_default_language=True)[sumber]¶

Fungsi ini dapat digunakan dalam URLconf akar dan Django akan otomatis menambahkan kode bahasa aktif saat ini pada semua pola URL ditentukan dalam i18n_patterns().

Mengatur prefix_default_language menjadi False memindahkan awalan dari bahasa awalan (LANGUAGE_CODE). Ini dapat berguna ketika menambahkan terjemahan pada situs yang ada sehingga URL saat ini tidak akan berubah.

Contoh pola URL:

from django.conf.urls.i18n import i18n_patterns
from django.urls import include, url

from about import views as about_views
from news import views as news_views
from sitemap.views import sitemap

urlpatterns = [
    path('sitemap.xml', sitemap, name='sitemap-xml'),
]

news_patterns = ([
    path('', news_views.index, name='index'),
    path('category/<slug:slug>/', news_views.category, name='category'),
    path('<slug:slug>/', news_views.details, name='detail'),
], 'news')

urlpatterns += i18n_patterns(
    path('about/', about_views.main, name='about'),
    path('news/', include(news_patterns, namespace='news')),
)

Setelah menentukan pola URL ini, Django akan otomatis menambahkan awalan bahasa ke pola URL yang telah ditambahkan oleh fungsi i18n_patterns. Contoh:

>>> from django.urls import reverse
>>> from django.utils.translation import activate

>>> activate('en')
>>> reverse('sitemap-xml')
'/sitemap.xml'
>>> reverse('news:index')
'/en/news/'

>>> activate('nl')
>>> reverse('news:detail', kwargs={'slug': 'news-slug'})
'/nl/news/news-slug/'

Dengan prefix_default_language=False dan LANGUAGE_CODE='en', URL akan menjadi:

>>> activate('en')
>>> reverse('news:index')
'/news/'

>>> activate('nl')
>>> reverse('news:index')
'/nl/news/'

Menterjemahkan pola URL¶

Pola URL dapat juga ditandai dapat diterjemahkan menggunakan fungsi gettext_lazy(). Contoh:

from django.conf.urls.i18n import i18n_patterns
from django.urls import include, path
from django.utils.translation import gettext_lazy as _

from about import views as about_views
from news import views as news_views
from sitemaps.views import sitemap

urlpatterns = [
    path('sitemap.xml', sitemap, name='sitemap-xml'),
]

news_patterns = ([
    path('', news_views.index, name='index'),
    path(_('category/<slug:slug>/'), news_views.category, name='category'),
    path('<slug:slug>/', news_views.details, name='detail'),
], 'news')

urlpatterns += i18n_patterns(
    path(_('about/'), about_views.main, name='about'),
    path(_('news/'), include(news_patterns, namespace='news')),
)

Setelah anda telah membuat terjemahan, fungsi reverse() akan mengembalikan URL dalam bahasa aktif. Contoh:

>>> from django.urls import reverse
>>> from django.utils.translation import activate

>>> activate('en')
>>> reverse('news:category', kwargs={'slug': 'recent'})
'/en/news/category/recent/'

>>> activate('nl')
>>> reverse('news:category', kwargs={'slug': 'recent'})
'/nl/nieuws/categorie/recent/'

Membalikkan dalam cetakan-cetakan¶

Jika URL lokal mendapatkan terbalik dalam cetakan mereka selalu menggunakan bahasa saat ini. Untuk menautkan ke sebuah URL dalam bahasa lain gunakan etiket cetakan language. Itu mengadakan bahasa yang diberikan dalam bagian cetakan tertutup:

{% load i18n %}

{% get_available_languages as languages %}

{% trans "View this category in:" %}
{% for lang_code, lang_name in languages %}
    {% language lang_code %}
    <a href="{% url 'category' slug=category.slug %}">{{ lang_name }}</a>
    {% endlanguage %}
{% endfor %}

Etiket language mengharapkan kode bahasa sebagai hanya argumen.

Berkas pesan¶

langkah pertama adalah membuat sebuah message file untuk bahasa baru. Sebuah berkas pesan adalah sebuah berkas teks-polos, mewakili bahasa tunggal, yang mengandung semua string terjemahan tersedia dan bagaimana mereka harus dibawakan dalam bahasa diberikan. Berkas-berkas pesan mempunyai ekstensi berkas .po.

Django datang dengan sebuah alat, django-admin makemessages 1, yang mengotomatiskan pembuatan dan perawatan dari berkas-berkas ini.

Untuk membuat atau memperbaharui sebuah berkas pesan, jalankan perintah ini:

django-admin makemessages -l de

...dimana de adalah locale name untuk berkas pesan anda ingin buat. Sebagai contoh, pt_BR untuk Brasil Portugis, de_AT untuk Austria Jerman atau id untuk Indonesia.

Tulisan ini harus berjalan dari satu atau dua tempat:

• Direktori akar untuk proyek Django anda (satu yang mengandung manage.py).
• Direktori akar dari satu dari aplikasi Django anda.

Tulisan berjalan terhadap pohon sumber proyek anda atau pohon sumber aplikasi anda dan menarik semua string ditandai untuk terjemahan (lihat Bagaimana Django menemukan terjemahan dan pastikan LOCALE_PATHS dikonfigurasi dengan benar). Itu membuat (atau memperbaharui) sebuah berkas pesan dalam direktori locale/LANG/LC_MESSAGES. Dalam contoh de, berkas akan berupa locale/de/LC_MESSAGES/django.po.

Ketika anda menjalankan makemessages dari direktori akar dari proyek anda, string dikeluarkan akan secara otomatis disebarkan pada berkas-berkas pesan yang sesuai. Yaitu, string dikeluarkan dari sebuah berkas dari sebuah aplikasi mengandung direktori locale akan masuk dalam berkas pesan dibawah direktori itu. Sebuah string dikeluarkan dari sebuah berkas dari sebuah aplikasi tanpa direktori locale akan salah satu masuk dalam berkas pesan dibawah direktori didaftar pertama dalam LOCALE_PATHS atau akan membangkitkan sebuah kesalahan jika LOCALE_PATHS adalah kosong.

Secara awalan django-admin makemessages 1 menguji setiap berkas yang mempunyai ekstensi berkas .html, .txt atau .py. Jika anda ingin menimpa awalan itu, gunakan pilihan --extension 2 atau -e untuk menentukan ekstensi berkas untuk diuji:

django-admin makemessages -l de -e txt

Mmeisahkan banyak ekstensi dengan koma dan/atau menggunakan -e atau --extension berkali-kali:

django-admin makemessages -l de -e html,txt -e xml

# Extraction from Python source files
[python: **.py]

# Extraction from Jinja2 templates
[jinja2: **.jinja]
extensions = jinja2.ext.with_

The format of .po files is straightforward. Each .po file contains a small bit of metadata, such as the translation maintainer's contact information, but the bulk of the file is a list of messages -- simple mappings between translation strings and the actual translated text for the particular language.

Sebagai contoh, jika aplikasi Django anda mengandung string terjemahan untuk teks "Welcome to my site.", seperti itu:

_("Welcome to my site.")

...kemudian django-admin makemessages 1 akan membuat sebuah berkas .po mengandung potongan berikut -- sebuah pesan:

#: path/to/python/module.py:23
msgid "Welcome to my site."
msgstr ""

Penjelasan cepat:

• msgid adalah string terjemahan, yang muncul dalam sumber. Jangan rubah itu.
• msgstr adalah dimana anda menaruh terjemahan bahasa-khusus. Itu mulai kosong, jadi itu adalah tanggungjawab anda merubah itu. pastikan anda menjaga kutipan disekitar terjemahan anda.
• Sebagai sebuah kenyamanan, setiap pesan termasuk, dalam bentuk dari baris komentar diawali dengan # dan bertempat diatas baris msgid, nama berkas dan nomor baris dari mana string terjemahan telah dikumpulkan sedikit demi sedikit.

Pesan-pesan panjang adalah kasus khusus. Ada, string pertama secara langsung setelah msgstr (atau msgid) adalah string kosong. Kemudian isi itu sendiri akan ditulis terhadap sedikit baris selanjutnya sebagai satu string per baris. String-string tersebut secara langsung disatukan. Jangan lupa buntutan ruang kosong dalam string; jika tidak, mereka akan dilekatkan bersama-sama tanpa ruang kosong!

Untuk menguji kembali semua kode sumber da cetakan untuk string terjemahan baru dan memperbaharui semua berkas pesan untuk semua bahasa, jalankan ini:

django-admin makemessages -a

Menyusun berkas-berkas pesan¶

Setelah anda membuat berkas pesan anda -- dan setiap kali anda membuat perubahan ke itu -- anda akan butuh menyusun itu menjadi bentuk lebih efesien, untuk digunakan oleh gettext. Lakukan ini dengan alat django-admin compilemessages 1.

Alat ini berjalan terhadap semua berkas .po tersedia dan membuat berkas .mo, yang adalah berkas biner dioptimalkan untu digunakan oleh gettext. Dalam direktori sama dari mana anda menjalankan django-admin makemessages 1, jalankan django-admin compilemessages 2 seperti ini:

django-admin compilemessages

Itu dia, terjemahan anda siap digunakan.

Pemecahan masalah: gettext() tidak benar mengenali python-format dalam string-string dengan tanda persen¶

In some cases, such as strings with a percent sign followed by a space and a string conversion type (e.g. _("10% interest")), gettext() incorrectly flags strings with python-format.

If you try to compile message files with incorrectly flagged strings, you'll get an error message like number of format specifications in 'msgid' and 'msgstr' does not match or 'msgstr' is not a valid Python format string, unlike 'msgid'.

Untuk memecahkan ini, anda dapat meloloskan tanda persen dengan menambahkan tanda persen kedua:

from django.utils.translation import gettext as _
output = _("10%% interest")

Atau anda dapat menggunakan no-python-format sehingga semua tanda persen diperlakukan sebagai harfiah.

# xgettext:no-python-format
output = _("10% interest")

Membuat berkas pesan dari kode sumber JavaScript¶

You create and update the message files the same way as the other Django message files -- with the django-admin makemessages tool. The only difference is you need to explicitly specify what in gettext parlance is known as a domain in this case the djangojs domain, by providing a -d djangojs parameter, like this:

django-admin makemessages -d djangojs -l de

This would create or update the message file for JavaScript for German. After updating message files, just run django-admin compilemessages the same way as you do with normal Django message files.

gettext pada Windows¶

This is only needed for people who either want to extract message IDs or compile message files (.po). Translation work itself just involves editing existing files of this type, but if you want to create your own message files, or want to test or compile a changed message file, download a precompiled binary installer.

You may also use gettext binaries you have obtained elsewhere, so long as the xgettext --version command works properly. Do not attempt to use Django translation utilities with a gettext package if the command xgettext --version entered at a Windows command prompt causes a popup window saying "xgettext.exe has generated errors and will be closed by Windows".

Menyesuaikan perintah makemessages¶

Jika anda ingin melewatkan parameter tambahan pada xgettext, anda butuh membuat perintah makemessages penyesuaian dan menimpa atribut xgettext_options nya:

from django.core.management.commands import makemessages

class Command(makemessages.Command):
    xgettext_options = makemessages.Command.xgettext_options + ['--keyword=mytrans']

Jika anda butuh lebih keluwesan, anda dapat juga menambahkan argumen baru ke perintah perintah makemessages  anda:

from django.core.management.commands import makemessages

class Command(makemessages.Command):

    def add_arguments(self, parser):
        super().add_arguments(parser)
        parser.add_argument(
            '--extra-keyword',
            dest='xgettext_keywords',
            action='append',
        )

    def handle(self, *args, **options):
        xgettext_keywords = options.pop('xgettext_keywords')
        if xgettext_keywords:
            self.xgettext_options = (
                makemessages.Command.xgettext_options[:] +
                ['--keyword=%s' % kwd for kwd in xgettext_keywords]
            )
        super().handle(*args, **options)

Tampilan mengalihkan set_language¶

set_language(request)[sumber]¶

As a convenience, Django comes with a view, django.views.i18n.set_language(), that sets a user's language preference and redirects to a given URL or, by default, back to the previous page.

Aktifkan tampilan ini dengan menambahkan baris berikut ke URLconf anda:

path('i18n/', include('django.conf.urls.i18n')),

(Catat bahwa contoh ini membuat tampilan tersedia pada /i18n/setlang/.)

The view expects to be called via the POST method, with a language parameter set in request. If session support is enabled, the view saves the language choice in the user's session. Otherwise, it saves the language choice in a cookie that is by default named django_language. (The name can be changed through the LANGUAGE_COOKIE_NAME setting.)

After setting the language choice, Django looks for a next parameter in the POST or GET data. If that is found and Django considers it to be a safe URL (i.e. it doesn't point to a different host and uses a safe scheme), a redirect to that URL will be performed. Otherwise, Django may fall back to redirecting the user to the URL from the Referer header or, if it is not set, to /, depending on the nature of the request:

• Untuk permintaan AJAX, fallback akan dialkukan hanya jika parameter next telah disetel. Sebaliknya sebuah kode keadaan 204 (Tidak ada Isi) akan dikembalikan.
• Untuk permintaan bukan-AJAX, fallback akan selalu dilakukan.

Ini adalah contoh kode cetakan HTML:

{% load i18n %}

<form action="{% url 'set_language' %}" method="post">{% csrf_token %}
    <input name="next" type="hidden" value="{{ redirect_to }}" />
    <select name="language">
        {% get_current_language as LANGUAGE_CODE %}
        {% get_available_languages as LANGUAGES %}
        {% get_language_info_list for LANGUAGES as languages %}
        {% for language in languages %}
            <option value="{{ language.code }}"{% if language.code == LANGUAGE_CODE %} selected{% endif %}>
                {{ language.name_local }} ({{ language.code }})
            </option>
        {% endfor %}
    </select>
    <input type="submit" value="Go" />
</form>

Dalam contoh ini, Django mencari URL dari halaman pada dimana pengguna akan dialihkan dalam variabel konteks redirect_to.

Secara jelas mengatur bahasa aktif¶

Anda mungkin ingin menyetel bahasa aktif untuk sesi saat ini secara jelas. Mungkin pilihan bahasa pengguna diambil dari sistem lain, sebagai contoh. Anda telah diperkenalkan pada django.utils.translation.activate(). Yang memberlakukan ke hanya rangkaian saat ini. Untuk bertahan bahasa untuk seluruh sesi, juga rubah LANGUAGE_SESSION_KEY dalam sesi:

from django.utils import translation
user_language = 'fr'
translation.activate(user_language)
request.session[translation.LANGUAGE_SESSION_KEY] = user_language

Anda biasaya ingin melakukan menggunakan kedua: django.utils.translation.activate() akan merubah bahasa ke rangkaian ini, dan merubah sesi membuat pilihan ini tetap ada di permintaan akan datang.

Jika anda tidak menggunakan sesi, bahasa akan terus ada dalam sebuah cookie, yang namanya dikonfigurasi dalam LANGUAGE_COOKIE_NAME. Sebagai contoh:

from django.conf import settings
from django.http import HttpResponse
from django.utils import translation
user_language = 'fr'
translation.activate(user_language)
response = HttpResponse(...)
response.set_cookie(settings.LANGUAGE_COOKIE_NAME, user_language)

Menggunakan terjemahan diluar tampilan dan cetakan¶

While Django provides a rich set of i18n tools for use in views and templates, it does not restrict the usage to Django-specific code. The Django translation mechanisms can be used to translate arbitrary texts to any language that is supported by Django (as long as an appropriate translation catalog exists, of course). You can load a translation catalog, activate it and translate text to language of your choice, but remember to switch back to original language, as activating a translation catalog is done on per-thread basis and such change will affect code running in the same thread.

Sebagai contoh:

from django.utils import translation

def welcome_translated(language):
    cur_language = translation.get_language()
    try:
        translation.activate(language)
        text = translation.gettext('welcome')
    finally:
        translation.activate(cur_language)
    return text

Memanggil fungsi ini dengan nilai 'de' akan memberikan anda "Willkommen", tanpa memperhatikan dari LANGUAGE_CODE dan bahasa disetel oleh middleware.

Fungsi-fungsi untuk minat tertentu adalah django.utils.translation.get_language() yang mengembalikan bahasa digunakan dalam thread saat ini, django.utils.translation.activate() yang mengaktifkan sebuah katalog terjemahan untuk thread saat ini, dan django.utils.translation.check_for_language() yang akan memeriksa jika bahasa diberikan adalah didukung oleh Django.

Untuk membantu menulis lebih kode ringkas, ada juga sebuah pengelola konteks django.utils.translation.override() yang menyimpan bahasa sat ini pada saat masuk dan menyimpan kembali itu pada saat keluar. Dengan itu, contoh diatas menjadi:

from django.utils import translation

def welcome_translated(language):
    with translation.override(language):
        return translation.gettext('welcome')

Cookie bahasa¶

Sejumlah pengatuan dapat digunakan untuk menyesuaikan pilihan cookie bahasa:

• LANGUAGE_COOKIE_NAME
• LANGUAGE_COOKIE_AGE
• LANGUAGE_COOKIE_DOMAIN
• LANGUAGE_COOKIE_PATH

Keahlian khusus dari terjemahan Django¶

Django's translation machinery uses the standard gettext module that comes with Python. If you know gettext, you might note these specialties in the way Django does translation:

• The string domain is django or djangojs. This string domain is used to differentiate between different programs that store their data in a common message-file library (usually /usr/share/locale/). The django domain is used for Python and template translation strings and is loaded into the global translation catalogs. The djangojs domain is only used for JavaScript translation catalogs to make sure that those are as small as possible.
• Django tidak menggunakan xgettext sendiri. Itu menggunakan Python dibungkus disekitar xgettext dan msgfmt. Ini kebanyakan untuk kenyamanan.

Bagaimana Django menemukan pilihan bahasa¶

Ketika anda telah menyiapkan terjemahan anda -- atau, jika anda hanya ingin menggunakan terjemahan yang datang dengan Django -- anda hanya butuh mengaktifkan terjemahan untuk aplikasi anda.

Dbelakang layar, Django mempunyai model yang sagat elastis dari memutuskan bahasa mana harus digunakan -- pemasangan-lebar, untuk pengguna tertentu, atau keduanya.

Untuk menyetel sebuah pilihan bahasa pemasangan-luas, setel LANGUAGE_CODE. Django menggunakan bahasa ini sebagai terjemahan awalan -- usaha akhir jika tidak ada terjemahan yang cocok ditemukan melalui satu dari metode-metode dengan middleware lokal (lihat dibawah).

Jika yang anda inginkan adalah menjalankan Django dengan bahasa asli anda semua anda butuhkan untuk lakukan adalah menyetel LANGUAGE_CODE dan memastikan message files 1 sesuai dan versi tersusun mereka (.mo) ada.

Jika anda ingin membiarkan setiap pengguna perorangan menentukan bahasa mana mereka pilih, kemudian anda juga butuh menggunakan LocaleMiddleware. LocaleMiddleware mengadakan pilihan bahasa berdasarkan pada data dari permintaan. Itu menyesuaikan isi untuk setiap pengguna.

Untuk menggunakan LocaleMiddleware, tambah 'django.middleware.locale.LocaleMiddleware' ke pengaturan MIDDLEWARE anda. Karena urutan middleware penting, ikuti panduan berikut:

• Pastikan itu adalah satu dari middleware pertama dipasang.
• It should come after SessionMiddleware, because LocaleMiddleware makes use of session data. And it should come before CommonMiddleware because CommonMiddleware needs an activated language in order to resolve the requested URL.
• Jika anda menggunakan CacheMiddleware, taruh LocaleMiddleware setelah itu.

Sebagai contoh, MIDDLEWARE anda mungkin terlihat seperti ini:

MIDDLEWARE = [
   'django.contrib.sessions.middleware.SessionMiddleware',
   'django.middleware.locale.LocaleMiddleware',
   'django.middleware.common.CommonMiddleware',
]

(Untuk lebih pada middleware, lihat middleware documentation 1.)

LocaleMiddleware mencoba menentukan pilihan bahasa pengguna dengan mengikuti algoritma ini:

• First, it looks for the language prefix in the requested URL. This is only performed when you are using the i18n_patterns function in your root URLconf. See Internasionalisasi: dalam pola URL for more information about the language prefix and how to internationalize URL patterns.

• Failing that, it looks for the LANGUAGE_SESSION_KEY key in the current user's session.

• Failing that, it looks for a cookie.

  Nama dari cookie digunakan adalah disetel oleh pengaturan LANGUAGE_COOKIE_NAME. (Nama awalan adalah django_language.)

• Failing that, it looks at the Accept-Language HTTP header. This header is sent by your browser and tells the server which language(s) you prefer, in order by priority. Django tries each language in the header until it finds one with available translations.

• Failing that, it uses the global LANGUAGE_CODE setting.

Catatan:

• In each of these places, the language preference is expected to be in the standard language format, as a string. For example, Brazilian Portuguese is pt-br.

• If a base language is available but the sublanguage specified is not, Django uses the base language. For example, if a user specifies de-at (Austrian German) but Django only has de available, Django uses de.

• Only languages listed in the LANGUAGES setting can be selected. If you want to restrict the language selection to a subset of provided languages (because your application doesn't provide all those languages), set LANGUAGES to a list of languages. For example:

  LANGUAGES = [
    ('de', _('German')),
    ('en', _('English')),
  ]
  

  Contoh-contoh ini membatasi bahasa-bahasa yang tersedia untuk pemilihan otomatis pada Jerman dan Inggris (dan subbahasa apapun, seperti de-ch atau en-us).

• If you define a custom LANGUAGES setting, as explained in the previous bullet, you can mark the language names as translation strings -- but use gettext_lazy() instead of gettext() to avoid a circular import.

  Ini adalah contoh sebuah berkas pengaturan:

  from django.utils.translation import gettext_lazy as _
  
  LANGUAGES = [
      ('de', _('German')),
      ('en', _('English')),
  ]
  

Once LocaleMiddleware determines the user's preference, it makes this preference available as request.LANGUAGE_CODE for each HttpRequest. Feel free to read this value in your view code. Here's a simple example:

from django.http import HttpResponse

def hello_world(request, count):
    if request.LANGUAGE_CODE == 'de-at':
        return HttpResponse("You prefer to read Austrian German.")
    else:
        return HttpResponse("You prefer to read another language.")

Catat bahwa, dengan terjemahan tetap (tanpa-middleware), bahasa di settings.LANGUAGE_CODE, selagi dengan terjemahan dinamis (middleware), itu di request.LANGUAGE_CODE.

Bagaimana Django menemukan terjemahan¶

At runtime, Django builds an in-memory unified catalog of literals-translations. To achieve this it looks for translations by following this algorithm regarding the order in which it examines the different file paths to load the compiled message files (.mo) and the precedence of multiple translations for the same literal:

1. The directories listed in LOCALE_PATHS have the highest precedence, with the ones appearing first having higher precedence than the ones appearing later.
2. Then, it looks for and uses if it exists a locale directory in each of the installed apps listed in INSTALLED_APPS. The ones appearing first have higher precedence than the ones appearing later.
3. Akhirnya, terjemahan dasar disediakan-Django dalam django/conf/locale digunakan sebagai sebuah fallback.

In all cases the name of the directory containing the translation is expected to be named using locale name notation. E.g. de, pt_BR, es_AR, etc.

Cara ini, anda dapat menulis aplikasi yang menyertakan terjemahan mereka sendiri, dan anda dapat menimpa terjemahan dasar dalam proyek anda. Atau, anda dapat cukup membangun proyek besar dari beberapa aplikasi dan menaruh semua terjemahan kedalam berkas pesan umum besar ke proyek anda susun. Pilihan ada di anda.

Semua gudang berkas pesan tersusun cara sama. Mereka adalah:

• Semua jalur-jalur terdaftar dalam LOCALE_PATHS di berkas pengaturan anda adalah dicari untuk 1/LC_MESSAGES/django.(po|mo)
• $APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
• $PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)

Untuk membuat berkas pesan, anda menggunakan , anda menggunakan alat django-admin makemessages . Dan anda menggunakan django-admin compilemessages untuk menghasilkan berkas-berkas biner .mo yang digunakan oleh gettext.

Anda dapat juga menjalankan django-admin compilemessages --settings=path.to.settings 1 untuk membuat penyusun mengolah semua direktori dalam pengaturan LOCALE_PATHS anda.

Menggunakan bahasa dasar bukan-Inggris¶

Django membuat anggapan umum bahwa string asli dalam proyek terjemahan ditulis dalam Inggris. Anda dapat memilih bahasa lain, tetapi harus waspada dari batasan tertentu:

• gettext only provides two plural forms for the original messages, so you will also need to provide a translation for the base language to include all plural forms if the plural rules for the base language are different from English.
• When an English variant is activated and English strings are missing, the fallback language will not be the LANGUAGE_CODE of the project, but the original strings. For example, an English user visiting a site with LANGUAGE_CODE set to Spanish and original strings written in Russian will see Russian text rather than Spanish.