Django プロジェクトを翻訳可能にするためには、Python コードやテンプレートに、多少のフックを加筆しなければなりません。このフックは 翻訳文字列 と呼ばれます。翻訳文字列は Django に「このテキストに対する翻訳が有効な場合、このテキストはエンドユーザの言語に翻訳すべきだ」ということを通知します。翻訳可能な文字列をマークすることは開発者の責任です。システムが翻訳できるのは指定された文字列だけなのです。
\nDjango は、翻訳文字列を メッセージファイル に抽出するユーティリティを提供します。このファイルがあるため、翻訳者が対象の言語において翻訳文字列に対応する文字列を用意することが簡単になります。翻訳者がメッセージファイルの中身を書き終わったら、それをコンパイルしなければなりません。このプロセスは GNU gettext ツー ルキットに依存しています。
\nこれが済めば、 Django はユーザの言語設定に従って、オンザフライでアプリケーションを利用可能な言語に翻訳するようになります。
\nDjango の国際化フックはデフォルトで有効になっており、これは、フレームワークの特定の箇所で i18n に関する小さなオーバーヘッドが発生することを意味します。国際化を使わない場合は、 USE_I18N = False を設定ファイルに記述してください。そうすれば Django は国際化の部品を読み込まないようにして多少の最適化をします。
翻訳対象の文字列を関数 gettext() で指定します。入力の手間を省くため、この関数は短い別名 _ としてインポートするのが慣例です。
この例では、"Welcome to my site." というテキストが翻訳文字列としてマークされています:
from django.http import HttpResponse\nfrom django.utils.translation import gettext as _\n\n\ndef my_view(request):\n output = _("Welcome to my site.")\n return HttpResponse(output)\n別名を付けなくても同じコードを書くことができます。次の例は、上の例とまったく同一です:
\nfrom django.http import HttpResponse\nfrom django.utils.translation import gettext\n\n\ndef my_view(request):\n output = gettext("Welcome to my site.")\n return HttpResponse(output)\n翻訳は、計算済みの値に適用されます。次の例は、上の2つの例とまったく同一です:
\ndef my_view(request):\n words = ["Welcome", "to", "my", "site."]\n output = _(" ".join(words))\n return HttpResponse(output)\n翻訳は変数にも適用されます。次の例もまた、上の例とまったく同一です:
\ndef my_view(request):\n sentence = "Welcome to my site."\n output = _(sentence)\n return HttpResponse(output)\n(上の 2 つの例のように変数や計算済みの値を使う場合の注意点として、Django の翻訳文字列検出ユーティリティ django-admin makemessages はこれらの文字列を検出できません。詳しくは後の makemessages の節で説明します。)
_() や gettext() に渡す文字列には、Pyton の標準の名前付き補完構文によるプレースホルダを使えます。例えば:
def my_view(request, m, d):\n output = _("Today is %(month)s %(day)s.") % {"month": m, "day": d}\n return HttpResponse(output)\nこのテクニックを使うと、言語ごとの翻訳でプレースホルダを並び替えられるようになります。例えば、英語の翻訳文 "Today is Nobember, 26." に対して、スペイン語では "Hoy es 26 de noviembre." となるように、月と日のプレースホルダの位置を入れ替えることができます。
この理由から、引数が複数ある場合には、固定引数を使った補完 (%s や %d) ではなく、名前付きの補完 (%(day)s) を使ってください。固定引数による補完を使った場合、プレースホルダを正しい順番で翻訳できない場合があります。
文字列抽出は xgettext コマンドで行われるため、Django がサポートするのは gettext がサポートする構文のみです。特に、Python の f-strings はまだ xgettext でサポートされておらず、JavaScript テンプレート文字列は gettext 0.21+ が必要です。
翻訳可能な文字列についてのヒントを翻訳者に示したい場合、文字列の直前の行で Translators キーワードでプレフィックスされたコメントを追加できます。例えば:
def my_view(request):\n # Translators: This message appears on the home page only\n output = gettext("Welcome to my site.")\nコメントは、後に記述された翻訳可能な文章に関連付けられた、結果の .po ファイル内に表示され、ほとんどの翻訳ツールで表示されます。
これはテンプレート内でも動作します。詳しくは テンプレートにおける翻訳者のためのコメント を参照してください。
\n翻訳しない文字列としてマークするためには、django.utils.translation.gettext_noop() を使ってください。文字列は、変数より後で翻訳されます。
ソース言語内に保持すべき構成文字列がある場合、これを使ってください。これは、システムやユーザー (たとえばデータベース内の文字列) を介して交換される一方で、最後の時点 (たとえばユーザに文字列が表示されるとき) で翻訳される必要があるからです。
\n複数形のメッセージを指定するには、関数 django.utils.translation.ngettext() を使ってください。
ngettext は 3 つの引数を取ります: 単数形の文字列、複数形の文字列、オブジェクトの数です。
この関数は、Django アプリケーションを数と 複数形 の複雑さが英語で 2 より大きい (その値にかかわらず、単数には 'object'、そして count が 1 ではない全ての場合に 'objects' となります。) 言語にローカライズさせる必要がある場合に役立ちます。
例:
\nfrom django.http import HttpResponse\nfrom django.utils.translation import ngettext\n\n\ndef hello_world(request, count):\n page = ngettext(\n "there is %(count)d object",\n "there are %(count)d objects",\n count,\n ) % {\n "count": count,\n }\n return HttpResponse(page)\nこの例では、オブジェクトの数値は count 変数として翻訳言語に渡されます。
複数形は、複雑で言語によって異なる動作をすることに注意してください。count と 1 の比較は正しいルールではないことがあります。以下のコードは洗練されて見えますが、いくつかの言語に対しては誤った結果を生み出します:
from django.utils.translation import ngettext\nfrom myapp.models import Report\n\ncount = Report.objects.count()\nif count == 1:\n name = Report._meta.verbose_name\nelse:\n name = Report._meta.verbose_name_plural\n\ntext = ngettext(\n "There is %(count)d %(name)s available.",\n "There are %(count)d %(name)s available.",\n count,\n) % {"count": count, "name": name}\nあなた自身の単数複数ロジックを実装しないでください。おそらく正しくなりません。このようなケースでは、以下のようなコードを考えてみてください。
\ntext = ngettext(\n "There is %(count)d %(name)s object available.",\n "There are %(count)d %(name)s objects available.",\n count,\n) % {\n "count": count,\n "name": Report._meta.verbose_name,\n}\n単語は複数の意味を持っている場合があります。例えば、英語の "May" は、月名と動詞を指します。翻訳者が異なる文脈でこれらの単語を正しく翻訳できるようにするには、django.utils.translation.pgettext() 関数、もしくは文字列が複数形を必要とする場合は django.utils.translation.npgettext() 関数を使うことができます。両方とも、第 1 変数として文脈文字列を取ります。
結果の .po ファイルで、文字列は同じ文字列に対する異なる文脈マーカーがあるのと同じ頻度で出現し (コンテキストは msgctxt 行に出現します)、これらそれぞれに対して翻訳者が異なる翻訳ができるようにします。
例:
\nfrom django.utils.translation import pgettext\n\nmonth = pgettext("month name", "May")\nもしくは:
\nfrom django.db import models\nfrom django.utils.translation import pgettext_lazy\n\n\nclass MyThing(models.Model):\n name = models.CharField(\n help_text=pgettext_lazy("help text for MyThing model", "This is the help text")\n )\nこれは .po ファイル内に以下のように出現します:
msgctxt "month name"\nmsgid "May"\nmsgstr ""\n文脈マーカーは、translate と blocktranslate テンプレートタグによってもサポートされています。
Lazy に、つまり遅延的に、値が呼ばれたときではなくアクセスされたときに文字列を翻訳するためには、django.utils.translation (名前の lazy 接尾辞ですぐ分かります) の翻訳関数の lazy バージョンを使ってください、
これらの関数は、Lazy な文字列参照を保持します -- 実際の翻訳ではありません。翻訳自体はテンプレートレンダリング内のように、文字列が文字列コンテキスト内で使われるときに行われます。
\nこれらの関数への呼び出しがモジュールのロード時に実行されるコードパスにある場合は、これは不可欠です。
\nこれは、モデル、フォーム、モデルフォームを定義するときに簡単に発生することができるものです。これは、Django がフィールドを実際にクラスレベルの属性にするように実装するためです。 そのため、以下のような場合は lazy な翻訳を使用してください:
\nverbose_name と help_text オプションの値Link to this heading#例えば、以下のモデルの name フィールドのヘルプテキストを翻訳するためには、以下のようにします:
\nfrom django.db import models\nfrom django.utils.translation import gettext_lazy as _\n\n\nclass MyThing(models.Model):\n name = models.CharField(help_text=_("This is the help text"))\nverbose_name オプションを使えば、ForeignKey、ManyToManyField や OneToOneField リレーションシップの名前を翻訳可能にできます:
class MyThing(models.Model):\n kind = models.ForeignKey(\n ThingKind,\n on_delete=models.CASCADE,\n related_name="kinds",\n verbose_name=_("kind"),\n )\nverbose_name と同様に、必要に応じて Django が自動的にタイトルケースに直すので、リレーションシップに対する小文字の冗長な名前テキストを提供する必要があります。
フォールバックの英語中心とモデルのクラス名を見ることによって Django が動作する冗長な名前の純粋な決定に頼るよりも、明示的な verbose_name と verbose_name_plural オプションを指定することが推奨されます:
from django.db import models\nfrom django.utils.translation import gettext_lazy as _\n\n\nclass MyThing(models.Model):\n name = models.CharField(_("name"), help_text=_("This is the help text"))\n\n class Meta:\n verbose_name = _("my thing")\n verbose_name_plural = _("my things")\ndescription を @display デコレーターに渡す。Link to this heading#モデルメソッドに対しては、display() デコレータの short_description 引数で Djangoと admin サイトへの翻訳が提供できます。
from django.contrib import admin\nfrom django.db import models\nfrom django.utils.translation import gettext_lazy as _\n\n\nclass MyThing(models.Model):\n kind = models.ForeignKey(\n ThingKind,\n on_delete=models.CASCADE,\n related_name="kinds",\n verbose_name=_("kind"),\n )\n\n @admin.display(description=_("Is it a mouse?"))\n def is_mouse(self):\n return self.kind.type == MOUSE_TYPE\ngettext_lazy() 呼び出しの結果は、他の Django コード内で文字列 (str オブジェクト) を使うときはいつでも使うことができますが、気まぐれな Python コードでうまく動作しないかもしれません。例えば、requests ライブラリが gettext_lazy オブジェクトを処理しないので、以下は動作しません:
body = gettext_lazy("I \\u2764 Django") # (Unicode :heart:)\nrequests.post("https://example.com/send", data={"body": body})\ngettext_lazy() オブジェクトを非 Django コードに渡す前にテキスト文字列にキャストすることで、この問題を防ぐことができます:
requests.post("https://example.com/send", data={"body": str(body)})\ngettext_lazy という長い名前を使いたくない場合は、次のように _ (アンダースコア) としてエイリアスできます。
from django.db import models\nfrom django.utils.translation import gettext_lazy as _\n\n\nclass MyThing(models.Model):\n name = models.CharField(help_text=_("This is the help text"))\nモデルやユーティリティ関数内で文字列に gettext_lazy() や ngettext_lazy() を使用してマークすることはよく行われます。これらのオブジェクトをコードの他の場所で扱う際には、誤って文字列に変換しないよう注意する必要があります。なぜなら、これらの変換は可能な限り遅延されるべきだからです（正しいロケールが効果を発揮するため）。これには、次に説明するヘルパー関数の使用が必要です。
複数の文字列に対して遅延翻訳 (n[p]gettext_lazy) を使用する場合、一般的に文字列を定義する時点では number 引数を知りません。そのため、 number 引数に整数ではなくキー名を渡すことが許可されています。そうすると、文字列の補間時に number がそのキーの辞書で検索されます。以下に例を示します:
from django import forms\nfrom django.core.exceptions import ValidationError\nfrom django.utils.translation import ngettext_lazy\n\n\nclass MyForm(forms.Form):\n error_message = ngettext_lazy(\n "You only provided %(num)d argument",\n "You only provided %(num)d arguments",\n "num",\n )\n\n def clean(self):\n # ...\n if error:\n raise ValidationError(self.error_message % {"num": number})\n文字列の中に名前のないプレースホルダが1つだけ含まれている場合は、 number 引数で直接補間できます:
class MyForm(forms.Form):\n error_message = ngettext_lazy(\n "You provided %d argument",\n "You provided %d arguments",\n )\n\n def clean(self):\n # ...\n if error:\n raise ValidationError(self.error_message % number)\nformat_lazy()Link to this heading#Python の str.format() メソッドは format_string や str.format() の引数に遅延 (lazy) 翻訳オブジェクトが含まれている場合には動作しません。その代わりに django.utils.text.format_lazy() を使うことができます。これは結果が文字列に含まれるときだけ str.format() メソッドを実行する遅延オブジェクトを作成します。たとえば、次のようになります:
from django.utils.text import format_lazy\nfrom django.utils.translation import gettext_lazy\n\n...\nname = gettext_lazy("John Lennon")\ninstrument = gettext_lazy("guitar")\nresult = format_lazy("{name}: {instrument}", name=name, instrument=instrument)\nこの場合、 result 内の遅延翻訳は、 result 自体が文字列で使用されるとき（通常はテンプレートのレンダリング時）にだけ文字列に変換されます。
翻訳を遅らせたいが、翻訳可能な文字列を別の関数の引数として渡さなければならない場合、この関数を遅延 (Lazy) 呼び出しでラップできます。たとえば次のようにします:
\nfrom django.utils.functional import lazy\nfrom django.utils.translation import gettext_lazy as _\n\n\ndef to_lower(string):\n return string.lower()\n\n\nto_lower_lazy = lazy(to_lower, str)\nその後、次のようにします:
\nlazy_string = to_lower_lazy(_("My STRING!"))\nget_language_info() 関数は、言語について詳細な情報を提供します:
>>> from django.utils.translation import activate, get_language_info\n>>> activate("fr")\n>>> li = get_language_info("de")\n>>> print(li["name"], li["name_local"], li["name_translated"], li["bidi"])\nGerman Deutsch Allemand False\nディクショナリの name、name_local、name_translated 属性は、言語の英語名、言語自体、カレントのアクティブ言語をそれぞれ含んでいます。bidi 属性は双方向性の言語に対してのみ True です。
言語情報のソースは django.conf.locale モジュールです。テンプレートコードでも、この情報に対して同じようにアクセスできます。以下を参照してください。
Django テンプレート 内での翻訳は 2 つのテンプレートタグと Pthon コードとはやや異なるシンタックスを使います。テンプレートでこれらのタグを使えるようにするには、{% load i18n %} をテンプレートの先頭に対して設置してください。全てのテンプレートタグと同じように、すでに i18n をロードしているテンプレートを extend している場合であっても、翻訳を使用する全てのテンプレートでロードする必要があります。
translate テンプレートタグLink to this heading#{% translate %} テンプレートタグは、(シングルクオートやダブルクオートで囲まれた) 定数文字列や変数コンテンツを翻訳します:
<title>{% translate "This is the title." %}</title>\n<title>{% translate myvar %}</title>\nnoop オプションが存在する場合、変数はそのままですが翻訳の対象外となります。将来的に翻訳を必要とするコンテンツを "もみ消している" ときに役立ちます:
<title>{% translate "myvar" noop %}</title>\n内部的には、インラインの翻訳は gettext() 呼び出しを使っています。
テンプレート var (上記の myvar) がタグに渡された場合、最初にランタイムで変数から文字列へと解決し、それからメッセージカタログ内でその文字列をルックアップします。
{% translate %} 内の文字列でテンプレート変数を混ぜることはできません。翻訳が変数 (プレースホルダ) とともに文字列を必要とする場合は、代わりに {% blocktranslate %} を使ってください。
翻訳された文字列を表示させずに取り出したい場合は、以下の構文が使用できます:
\n{% translate "This is the title" as the_title %}\n\n<title>{{ the_title }}</title>\n<meta name="description" content="{{ the_title }}">\n実際には、テンプレート内の複数の場所で使用できる文字列を取得したり、他のテンプレートタグやフィルタリングするための引数として出力を使用したりする目的でこれを使うことになるでしょう:
\n{% translate "starting point" as start %}\n{% translate "end point" as end %}\n{% translate "La Grande Boucle" as race %}\n\n<h1>\n <a href="/" title="{% blocktranslate %}Back to '{{ race }}' homepage{% endblocktranslate %}">{{ race }}</a>\n</h1>\n<p>\n{% for stage in tour_stages %}\n {% cycle start end %}: {{ stage }}{% if forloop.counter|divisibleby:2 %}<br>{% else %}, {% endif %}\n{% endfor %}\n</p>\n{% translate %} は、context キーワードを使う 文脈マーカー もサポートしています:
{% translate "May" context "month name" %}\nblocktranslate テンプレートタグLink to this heading#translate タグとは対照的に、 blocktranslate タグはプレースホルダーを使うことで、リテラルその他の内容からなる複雑な文章を翻訳できます:
{% blocktranslate %}This string will have {{ value }} inside.{% endblocktranslate %}\nオブジェクトの object 属性にアクセスしたり、テンプレートフィルタを使ったりといったテンプレート式を翻訳するには、その式を翻訳ブロック内で使うローカル変数に結びつける必要があります。たとえば、次のようにします:
{% blocktranslate with amount=article.price %}\nThat will cost $ {{ amount }}.\n{% endblocktranslate %}\n\n{% blocktranslate with myvar=value|filter %}\nThis will have {{ myvar }} inside.\n{% endblocktranslate %}\n単一の blocktranslate タグ内で複数の式を使うこともできます:
{% blocktranslate with book_t=book|title author_t=author|title %}\nThis is {{ book_t }} by {{ author_t }}\n{% endblocktranslate %}\n他のブロックタグ (例えば {% for %} や {% if %}) は blocktranslate タグの中では使えません。
ブロック引数の解決に失敗した場合、 blocktranslate は deactivate_all() 関数を用いて、現在アクティブな言語を一時的に非アクティブにすることで、デフォルトの言語にフォールバックします。
このタグは複数形にも対応しています。使用するには:
\nカウンタの値を count という名前で指定し結び付けます。この値は正しい複数形の選択に使用されます。
{% blocktranslate %} と {% endblocktranslate %} のタグの中で単数形と複数形を {% plural %} タグで区切って指定してください。
例:
\n{% blocktranslate count counter=list|length %}\nThere is only one {{ name }} object.\n{% plural %}\nThere are {{ counter }} {{ name }} objects.\n{% endblocktranslate %}\nより複雑な例:
\n{% blocktranslate with amount=article.price count years=i.length %}\nThat will cost $ {{ amount }} per year.\n{% plural %}\nThat will cost $ {{ amount }} per {{ years }} years.\n{% endblocktranslate %}\nカウンターの値の追加に複数化機能とローカル変数への値のバインドの両方を使用する場合、 blocktranslate 構文は内部的に ngettext 呼び出しに変換されることに注意してください。つまり、 ngettext 変数に関する注意事項 と同じことに気を付ける必要があります。
URLの逆引きは blocktranslate 内では行えないので、事前に取得（保存）しておく必要があります:
{% url 'path.to.view' arg arg2 as the_url %}\n{% blocktranslate %}\nThis is a URL: {{ the_url }}\n{% endblocktranslate %}\n翻訳された文字列を表示させずに取り出したい場合は、以下の構文が使用できます:
\n{% blocktranslate asvar the_title %}The title is {{ title }}.{% endblocktranslate %}\n<title>{{ the_title }}</title>\n<meta name="description" content="{{ the_title }}">\n実際には、テンプレート内の複数の場所で使用できる文字列を取得したり、他のテンプレートタグやフィルタリングするための引数として出力を使用したりする目的でこれを使うことになるでしょう:
\n{% blocktranslate %} は、context キーワードを使う 文脈マーカー もサポートしています:
{% blocktranslate with name=user.username context "greeting" %}Hi {{ name }}{% endblocktranslate %}\n{% blocktranslate %} タグのもう1つの機能は、trimmed オプションです。このオプションは、{% blocktranslate %} タグのコンテンツの先頭と末尾から改行文字を削除し、行の先頭と末尾の空白を置き換え、すべての行を空白文字で区切って1行に結合します。これは、{% blocktranslate %} タグのコンテンツをインデントしても、インデント文字が対応する .po ファイルのエントリに含まれないようにするのに非常に便利で、翻訳作業が簡単になります。
例えば、次の {% blocktranslate %} タグ:
{% blocktranslate trimmed %}\n First sentence.\n Second paragraph.\n{% endblocktranslate %}\nの出力結果は .po ファイル内では "First sentence. Second paragraph." となります。対照に、 trimmed オプションが指定されていない場合は "\\n First sentence.\\n Second paragraph.\\n" となります。
Pythonコード の場合と同様に、これらの翻訳者向けのメモはコメントを使用して指定できます。comment タグを使用する場合がその一例です：
{% comment %}Translators: View verb{% endcomment %}\n{% translate "View" %}\n\n{% comment %}Translators: Short intro blurb{% endcomment %}\n<p>{% blocktranslate %}A multiline translatable\nliteral.{% endblocktranslate %}</p>\nまたは 一行コメント構文 {# ... ... #} で:
{# Translators: Label of a button that triggers search #}\n<button type="submit">{% translate "Go" %}</button>\n\n{# Translators: This is a text of the base template #}\n{% blocktranslate %}Ambiguous translatable block of text{% endblocktranslate %}\nテンプレートの中で言語を選択したい場合、 language テンプレートタグが使用できます:
{% load i18n %}\n\n{% get_current_language as LANGUAGE_CODE %}\n<!-- Current language: {{ LANGUAGE_CODE }} -->\n<p>{% translate "Welcome to our page" %}</p>\n\n{% language 'en' %}\n {% get_current_language as LANGUAGE_CODE %}\n <!-- Current language: {{ LANGUAGE_CODE }} -->\n <p>{% translate "Welcome to our page" %}</p>\n{% endlanguage %}\n"Welcome to our page" は、1つめのコードでは現在の言語を使って表示されますが、2つめのコードでは常に英語になります。
\nJavaScript に対する翻訳には、いくつか問題があります:
\nJavaScript コードは gettext 実行にアクセスできません。
JavaScript コードは .po や .mo ファイルにアクセスできません; サーバーによって配布される必要があります。
JavaScript 用の翻訳カタログはできる限り小さくなければなりません。
Django には、これらの問題に対する総合的な解決策が用意されています: 翻訳を JavaScript に渡し、gettext などを JavaScript 内から呼び出せるようにする方法です。
主な解決策は以下の JavaScriptCatalog ビューです。これは、gettext を擬似的に再現する関数と翻訳文字列の配列で JavaScript コードライブラリを生成します。
JavaScriptCatalog ビューLink to this heading#gettext インターフェイスを擬似的に再現する関数と翻訳文字列の配列で、JavaScriptのコードライブラリを生成するビューです。
属性
\nビューの出力に追加する文字列を含む翻訳ドメインです。デフォルトは 'djangojs' です。
インストールされたアプリケーション間の application names のリストです。これらのアプリケーションは locale ディレクトリを含んでいる必要があります。これらのカタログに加えて (常に含まれている) LOCALE_PATHS 内で見つかった全てのカタログは、1 つのカタログに統合されます。デフォルトは None で、全ての INSTALLED_APPS からの利用可能な翻訳は JavaScript の出力に渡されることを意味します。
デフォルト値を使った例:
\nfrom django.views.i18n import JavaScriptCatalog\n\nurlpatterns = [\n path("jsi18n/", JavaScriptCatalog.as_view(), name="javascript-catalog"),\n]\n独自のパッケージを使った例:
\nurlpatterns = [\n path(\n "jsi18n/myapp/",\n JavaScriptCatalog.as_view(packages=["your.app.label"]),\n name="javascript-catalog",\n ),\n]\nルートの URLconf が i18n_patterns()、JavaScriptCatalog を使っている場合、カタログが正しく生成されるように i18n_patterns() によるラップも必要となります。
i18n_patterns() を使った例:
from django.conf.urls.i18n import i18n_patterns\n\nurlpatterns = i18n_patterns(\n path("jsi18n/", JavaScriptCatalog.as_view(), name="javascript-catalog"),\n)\n翻訳の優先順位は、packages 引数で後に現れるパッケージの方が、最初に現れるものよりも高くなります。これは、同じリテラルに対する翻訳が衝突する場合に重要です。
サイト上で複数の JavaScriptCatalog ビューを使っていてそのうちのいくつかが同じ文字列を定義している場合、最後にロードされたカタログ内の文字列が優先されます。
カタログを使うには、以下のように動的に生成されたスクリプトを参照してください:
\n<script src="{% url 'javascript-catalog' %}"></script>\nこれは、reverse URL を使用して、JavaScript カタログビューの URL をルックアップします。カタログがロードされると、JavaScript コードは以下のメソッドを使えるようになります:
\ngettext
ngettext
interpolate
get_format
gettext_noop
pgettext
npgettext
pluralidx
gettextLink to this heading#gettext 関数は、Python コード内の標準の gettext インターフェースと同じように動作します:
document.write(gettext("this is to be translated"))\nngettextLink to this heading#ngettext 関数は単語やフレーズを複数形にするインターフェースを提供します:
const objectCount = 1 // or 0, or 2, or 3, ...\nconst string = ngettext(\n 'literal for the singular case',\n 'literal for the plural case',\n objectCount\n);\ninterpolateLink to this heading#interpolate 関数は表示形式の文字列の動的な記入をサポートします。補完の構文は Python を模しているので、interpolate 関数は位置および名前付きの補完の両方をサポートします。
位置による補完: obj は、表示されるのと同じ順番で要素の値が一致する fmt プレースホルダ内で連続的に補完される JavaScript Array オブジェクトを含んでいます。例えば:
const formats = ngettext(\n 'There is %s object. Remaining: %s',\n 'There are %s objects. Remaining: %s',\n 11\n);\nconst string = interpolate(formats, [11, 20]);\n// string is 'There are 11 objects. Remaining: 20'\n名前付きの補完: このモードは named パラメータを true として渡すことで選択されます。obj は JavaScript オブジェクトや結合配列を含みます。例えば:
const data = {\n count: 10,\n total: 50\n};\n\nconst formats = ngettext(\n 'Total: %(total)s, there is %(count)s object',\n 'there are %(count)s of a total of %(total)s objects',\n data.count\n);\nconst string = interpolate(formats, data, true);\nただし文字列補間は、やり過ぎるべきではありません。これはまだ JavaScript なので、コードは何度も正規表現による置換を行う必要があります。これは Python の文字列補間ほど速くはないので、本当に必要な場合（例えば、ngettext と組み合わせて適切な複数形を生成する場合など）に限定してください。
get_formatLink to this heading#get_format 関数は設定済みの i18n 表示形式設定にアクセスでき、与えられた設定名に対して表示形式文字列を取り出します:
document.write(get_format('DATE_FORMAT'));\n// 'N j, Y'\n以下の設定に対してアクセスします:
\nこれは、Python によってレンダリングされる値と一貫性を持った表示形式を保守するために役立ちます。
\ngettext_noopLink to this heading#これは gettext 関数をエミュレートしますが、何もせず、渡されたものをそのまま返します:
document.write(gettext_noop("this will not be translated"))\nこれは、将来的に翻訳が必要なコードの部分をもみ消しておくのに役立ちます。
\npgettextLink to this heading#pgettext 関数は Python の変数 (pgettext()) のように動作し、文脈的に翻訳される単語を提供します:
document.write(pgettext("month name", "May"))\nnpgettextLink to this heading#npgettext 関数も Python 変数 (npgettext()) のように動作し、複数形の 文脈的に翻訳される単語を提供します:
document.write(npgettext('group', 'party', 1));\n// party\ndocument.write(npgettext('group', 'party', 2));\n// parties\npluralidxLink to this heading#pluralidx 関数は pluralize テンプレートフィルタと同じように動作し、与えられた count が単語の複数形を使うべきかどうかを決めます:
document.write(pluralidx(0));\n// true\ndocument.write(pluralidx(1));\n// false\ndocument.write(pluralidx(2));\n// true\n最も単純なケースでは、独自の複数形が必要ない場合、これは整数 1 に対して false を返し、他の数に対して true を返します。
ただし、複数形は全ての言語でこのようにシンプルではありません。言語が複数形をサポートしていない場合、空の値が渡されます。
\n加えて、複数形に関して複雑なルールが存在する場合、カタログビューは条件付きの表現をレンダリングします。これは、値を true (複数形) と false (複数形 ではない ) のどちらにするかを評価します。
JSONCatalog ビューLink to this heading#他のクライアントサイドのライブラリを使って翻訳を扱うためには、JSONCatalog を利用するのがいいでしょう。JavaScriptCatalog と似ていますが、JSON のレスポンスを返します。
使える値を知るには、JavaScriptCatalog を参照してください。また、domain と packages 属性を使用してください。
レスポンスの形式は以下の通りです:
\n{\n "catalog": {\n # Translations catalog\n },\n "formats": {\n # Language formats for date, time, etc.\n },\n "plural": "..." # Expression for plural forms, or null.\n}\nたくさんの JavaScript/JSON i18n ビューは全てのリクエストで .mo ファイルからカタログを生成します。出力は一定なので、少なくとも与えられたサイトのバージョンに対しては、キャッシュが有力な選択肢となります。
サーバーサイドのキャッシシュは CPU の負担を軽減します。 cache_page() デコレータを使うと簡単に実装できます。翻訳を変更したときにキャッシュの無効部分をトリガーするには、以下の例にあるようにバージョンに依存したキープレフィックスを使ってください。もしくは、バージョンに依存した URL でビューをマッピングしてください:
from django.views.decorators.cache import cache_page\nfrom django.views.i18n import JavaScriptCatalog\n\n# The value returned by get_version() must change when translations change.\nurlpatterns = [\n path(\n "jsi18n/",\n cache_page(86400, key_prefix="jsi18n-%s" % get_version())(\n JavaScriptCatalog.as_view()\n ),\n name="javascript-catalog",\n ),\n]\nクライアントサイドのキャッシュは帯域を節約し、サイトの読み込みを速くします。ETags (ConditionalGetMiddleware) を使っている場合、すでに適用済みです。それ以外の場合は、条件付きデコレータ を参照してみてください。以下の例では、アプリケーションサーバを再起動するとキャッシュの効力がなくなります:
from django.utils import timezone\nfrom django.views.decorators.http import last_modified\nfrom django.views.i18n import JavaScriptCatalog\n\nlast_modified_date = timezone.now()\n\nurlpatterns = [\n path(\n "jsi18n/",\n last_modified(lambda req, **kw: last_modified_date)(\n JavaScriptCatalog.as_view()\n ),\n name="javascript-catalog",\n ),\n]\nデプロイ手順の一環として、JavaScript カタログを事前に生成し、静的ファイルとして提供することもできます。この革新的な手法は、django-statici18n によって実装されています。
\nDjango には、URL パターンを国際化するための 2 つの仕組みが用意されています:
\nLocaleMiddleware が、リクエストされた URL からアクティブにする言語を検出できるようにするため、URL パターンのルートに言語のプレフィックスを追加します。
URL パターン自体を django.utils.translation.gettext_lazy() 関数を通じて翻訳可能にする。
この関数は、ルートの URLconf で使うことができ、Django は自動的に現在アクティブな言語のコードを i18n_patterns() で定義された全ての URL パターンの先頭に追加します。
prefix_default_language を False にセットすると、デフォルト言語 (LANGUAGE_CODE) からプレフィックスを除去します。これは、現在の URL を変更しないよう既存のサイトに翻訳を追加するとき、役に立ちます。
URL パターンの例:
\nfrom django.conf.urls.i18n import i18n_patterns\nfrom django.urls import include, path\n\nfrom about import views as about_views\nfrom news import views as news_views\nfrom sitemap.views import sitemap\n\nurlpatterns = [\n path("sitemap.xml", sitemap, name="sitemap-xml"),\n]\n\nnews_patterns = (\n [\n path("", news_views.index, name="index"),\n path("category/<slug:slug>/", news_views.category, name="category"),\n path("<slug:slug>/", news_views.details, name="detail"),\n ],\n "news",\n)\n\nurlpatterns += i18n_patterns(\n path("about/", about_views.main, name="about"),\n path("news/", include(news_patterns, namespace="news")),\n)\nこれらの URL パターンを定義すると、Django は自動的に i18n_patterns 関数で追加された URL パターンに言語プレフィックスを追加します。例:
>>> from django.urls import reverse\n>>> from django.utils.translation import activate\n\n>>> activate("en")\n>>> reverse("sitemap-xml")\n'/sitemap.xml'\n>>> reverse("news:index")\n'/en/news/'\n\n>>> activate("nl")\n>>> reverse("news:detail", kwargs={"slug": "news-slug"})\n'/nl/news/news-slug/'\nprefix_default_language=False と LANGUAGE_CODE='en' を使うと、URL は以下のようになります:
>>> activate("en")\n>>> reverse("news:index")\n'/news/'\n\n>>> activate("nl")\n>>> reverse("news:index")\n'/nl/news/'\nURL パターンは、gettext_lazy() 関数を使って、翻訳可能にマークすることもできます。例えば:
from django.conf.urls.i18n import i18n_patterns\nfrom django.urls import include, path\nfrom django.utils.translation import gettext_lazy as _\n\nfrom about import views as about_views\nfrom news import views as news_views\nfrom sitemaps.views import sitemap\n\nurlpatterns = [\n path("sitemap.xml", sitemap, name="sitemap-xml"),\n]\n\nnews_patterns = (\n [\n path("", news_views.index, name="index"),\n path(_("category/<slug:slug>/"), news_views.category, name="category"),\n path("<slug:slug>/", news_views.details, name="detail"),\n ],\n "news",\n)\n\nurlpatterns += i18n_patterns(\n path(_("about/"), about_views.main, name="about"),\n path(_("news/"), include(news_patterns, namespace="news")),\n)\n翻訳を作成した後に、reverse() 関数はアクティブな言語で URL を返します。例えば:
>>> from django.urls import reverse\n>>> from django.utils.translation import activate\n\n>>> activate("en")\n>>> reverse("news:category", kwargs={"slug": "recent"})\n'/en/news/category/recent/'\n\n>>> activate("nl")\n>>> reverse("news:category", kwargs={"slug": "recent"})\n'/nl/nieuws/categorie/recent/'\nローカライズされた URL がテンプレート内でリバースされる場合、常に現在の言語が使用されます。他の言語の URL にリンクを貼るには、language テンプレートタグを使ってください。これは、テンプレートの囲まれた範囲内で、指定された言語を有効化します:
{% load i18n %}\n\n{% get_available_languages as languages %}\n\n{% translate "View this category in:" %}\n{% for lang_code, lang_name in languages %}\n {% language lang_code %}\n <a href="{% url 'category' slug=category.slug %}">{{ lang_name }}</a>\n {% endlanguage %}\n{% endfor %}\nlanguage タグは引数のみとして言語コードを予期します。
アプリケーションの文字列リテラルが後の翻訳にためにタグづけされ終わったら、翻訳自体を記述する (もしくは取得する) 必要があります。以下は、その方法です。
\n最初のステップは、新しい言語に対する message file を作成することです。メッセージファイルはプレーンテキストファイルで、単一の言語を記述します。このファイルは、全ての翻訳可能な文字列とそれらがどのように与えられた言語で表示されるかを含みます。メッセージファイルは .po ファイル拡張子を持ちます。
Djangoには django-admin makemessages というツールが用意してあり、これらのファイルの作成と保全を自動化します。
メッセージファイルを作成または更新するには、以下のコマンドを実行してください:
\ndjango-admin makemessages -l de\n...ここでの de は作成したいメッセージファイルに対するロケール名 locale name です。例えば、ブラジル系のポルトガル語に対する pt_BR、オーストリア系のドイツ語に対する de_AT、インドネシアに対する id などです。
スクリプトは、2 つの場所のうち 1 つから実行する必要があります:
\nDjango プロジェクトのルートディレクトリ (manage.py を含むところ)。
Django アプリケーションのルートディレクトリ。
スクリプトは、プロジェクトのソースツリーもしくはアプリケーションのソースツリーを通じて実行され、翻訳用にマークされた全ての文字列 (Djangoはどうやって翻訳を見つけるのか？ を参照して LOCALE_PATHS を正しく設定してください) を抽出します。ディレクトリ locale/LANG/LC_MESSAGES にメッセージファイルを作成 (もしくは更新) します。de の例では、ファイルは locale/de/LC_MESSAGES/django.po となります。
プロジェクトのルートディレクトリから makemessages を実行したとき、抽出された文字列は自動的に適切なメッセージファイルへと分配されます。つまり、locale ディレクトリを含むアプリケーションのファイルから抽出された文字列は、そのディレクトリ下のメッセージファイルに格納されます。locale ディレクトリがないアプリケーションのファイルから抽出された文字列は、LOCALE_PATHS 内に最初にリストアップされたディレクトリ下にあるメッセージファイルか、もしくは LOCALE_PATHS が空の場合はエラーを生成します。
デフォルトでは django-admin makemessages は .html 、 .txt または py のファイル拡張子を持つファイルを全て検査します。このデフォルトの動作をオーバーライドしたい場合は、 --extension か -e オプションを使って検査するファイル拡張子を指定します:
django-admin makemessages -l de -e txt\n複数の拡張子をカンマで区切るか、-e または --extension を複数回使用してください:
django-admin makemessages -l de -e html,txt -e xml\n各 .po ファイルは、翻訳保守者の連絡先情報などのわずかなメタデータを含みますが、大部分は メッセージ のリストです。これは、特定の言語に対する、翻訳文字列と実際の翻訳済みテキストのマッピングです。
例えば以下のように、Django アプリケーションが "Welcome to my site." に対する翻訳文字列を含んでいる場合、:
_("Welcome to my site.")\n...それから django-admin makemessages は .po ファイルを生成し、そのファイルは以下のようなスニペットを含みます -- メッセージ:
#: path/to/python/module.py:23\nmsgid "Welcome to my site."\nmsgstr ""\n簡単に説明すると:
\nmsgid は翻訳文字列で、ソース内に存在します。変更しないでください。
msgstr はあなたが言語に対応する翻訳を記述する場所です。これは空の状態から始まるので、変更するのはあなたの役割です。翻訳をクオートで囲むようにしてください。
利便性のため、各メッセージは、# でプレフィックスされ msgid 行の直前に位置するコメント行の形式の中に、翻訳文字列がどこから拾い集められたかを示すファイル名と行数を含みます。
長いメッセージは特殊なケースです。そこでは、msgstr (もしくは msgid) 直後の最初の文字列は空の文字列です。それからコンテンツ自身が行ごとに 1 つの文字列として次の数行にわたって記述されます。これらの文字列は直接連結されます。文字列内で最後のスペースを忘れないでください; さもなくば、空白スペースなしで接合されることになります！
新しい翻訳文字列に対して全てのコードとテンプレートを再検査して 全ての 言語に対する全てのメッセージファイルを更新するには、以下を実行してください:
\ndjango-admin makemessages -a\nメッセージファイルを作成した後 -- そして変更を加えたときそれぞれで -- gettext による使用のために、より効率的な形式にコンパイルする必要があります。django-admin compilemessages ユーティリティを利用してください。
このツールは、全ての有効な .po ファイルを通じて動作し、.mo ファイルを生成します。これは gettext による使用のために最適化されたバイナリファイルです。django-admin makemessages を実行した同じディレクトリで、以下のように django-admin compilemessages を実行してください:
django-admin compilemessages\nこれで終わりです。翻訳は使う準備ができました。
\n\n\ngettext() がパーセント文字を伴う文字列内で python-format を誤って見つけてしまうLink to this heading#例えば、パーセント記号に続いて空白と 文字列変換タイプ がある文字列（例: _("10% interest")）などに、gettext() は誤って python-format で文字列をフラグ付けすることがあります。
誤ってフラグが立てられた文字列でメッセージファイルをコンパイルしようとすると、number of format specifications in 'msgid' and 'msgstr' does not match もしくは 'msgstr' is not a valid Python format string, unlike 'msgid'. といったエラーが発生します。
これを解決するには、パーセント文字を 2 つ重ねてエスケープします:
\nfrom django.utils.translation import gettext as _\n\noutput = _("10%% interest")\nもしくは no-python-format を使ってパーセント文字がリテラルとして扱われるようにします:
# xgettext:no-python-format\noutput = _("10% interest")\n他の Django メッセージファイルと同じ方法で (django-admin makemessages ツールを使って) 作成や更新を行います。唯一の違いは、-d djangojs パラメータを提供することによって、gettext 用語がドメインであること (このケースでは djangojs ドメイン) を、以下のように明示的に指定する必要があることです:
django-admin makemessages -d djangojs -l de\nこれは、ドイツ語に対して JavaScript 用のメッセージファイルを作成または更新します。メッセージファイルの更新後、通常の Django ファイルと同様の方法で django-admin compilemessages を実行してください。
gettextLink to this heading#これはメッセージ ID を抽出したり、メッセージファイル(.po)をコンパイルしたい人だけが必要です。翻訳作業そのものは既存のこの種類のファイルを編集することになりますが、独自のメッセージファイルを作成したい場合や、変更したメッセージファイルをテストしたりコンパイルしたりしたい場合は、 コンパイル済みのバイナリインストーラ をダウンロードしてください。
xgettext --version コマンドが正しく動作する限り、他の場所で入手した gettext バイナリを使うこともできます。Windows のコマンドプロンプトでコマンド xgettext --version を入力すると、ポップアップウィンドウに "xgettext.exe has generated errors and will be closed by Windows" と表示される場合は、 gettext パッケージを使って Django の翻訳ユーティリティを使おうとしないでください。
makemessages コマンドをカスタマイズするLink to this heading#xgettext に追加のパラメータを渡したい場合、独自の makemessages コマンドを作成して、その xgettext_options 属性をオーバーライドする必要があります:
from django.core.management.commands import makemessages\n\n\nclass Command(makemessages.Command):\n xgettext_options = makemessages.Command.xgettext_options + ["--keyword=mytrans"]\nもっと柔軟に使う必要があるとき場合には、makemessages コマンドに新しい引数を追加することもできます:
from django.core.management.commands import makemessages\n\n\nclass Command(makemessages.Command):\n def add_arguments(self, parser):\n super().add_arguments(parser)\n parser.add_argument(\n "--extra-keyword",\n dest="xgettext_keywords",\n action="append",\n )\n\n def handle(self, *args, **options):\n xgettext_keywords = options.pop("xgettext_keywords")\n if xgettext_keywords:\n self.xgettext_options = makemessages.Command.xgettext_options[:] + [\n "--keyword=%s" % kwd for kwd in xgettext_keywords\n ]\n super().handle(*args, **options)\nset_language リダイレクトビューLink to this heading#利便性のために、 Django にはビュー django.views.i18n.set_language() が付属しており、 ユーザの言語設定を行い、指定された URL にリダイレクトします。デフォルトでは前のページに戻ります。
URLconfに以下の行を追加して、このビューを有効にします:
\npath("i18n/", include("django.conf.urls.i18n")),\n(この例では /i18n/setlang/ でビューを利用できるようにしていることに注意してください)。
このビューは POST メソッドで呼び出され、 language パラメータがリクエストに設定されることを想定しています。セッションサポートが有効な場合、ビューは言語選択をユーザのセッションに保存します。また、デフォルトでは django_language という名前のクッキーにも言語選択を保存します。(この名前は LANGUAGE_COOKIE_NAME 設定で変更できます)。
言語選択を設定した後、Django は POST または GET データの next パラメータを探します。もしそれが見つかり、 Django が安全な URL (つまり、別のホストを指しておらず、安全なスキームを使っている) と判断した場合、その URL へのリダイレクトが実行されます。そうでない場合、 Django はリクエストの性質に応じて、 Referer ヘッダの URL にリダイレクトしたり、ヘッダが設定されていない場合は / にリダイレクトしたりします:
リクエストが(Accept HTTPヘッダに基づいて)HTMLコンテンツを受け入れる場合、フォールバックは常に実行されます。
リクエストがHTMLを受け付けない場合、 next パラメータが指定されている場合のみフォールバックが実行されます。そうでない場合はステータスコード 204 (No Content) が返されます。
以下はHTMLテンプレートコードの例です:
\n{% load i18n %}\n\n<form action="{% url 'set_language' %}" method="post">{% csrf_token %}\n <input name="next" type="hidden" value="{{ redirect_to }}">\n <select name="language">\n {% get_current_language as LANGUAGE_CODE %}\n {% get_available_languages as LANGUAGES %}\n {% get_language_info_list for LANGUAGES as languages %}\n {% for language in languages %}\n <option value="{{ language.code }}"{% if language.code == LANGUAGE_CODE %} selected{% endif %}>\n {{ language.name_local }} ({{ language.code }})\n </option>\n {% endfor %}\n </select>\n <input type="submit" value="Go">\n</form>\nこの例では、 Django は redirect_to コンテキスト変数で、ユーザがリダイレクトされるページの URL を調べます。
明示的に、現在のセッションに対して、アクティブな言語をセットしたくなるかもしれません。例えば、他のシステムを活用すれば、ユーザの言語設定を取得できます。django.utils.translation.activate() はすでに紹介済みですね。これは現在のスレッドに対してのみ適用されます。セッション全体の言語をクッキーに恒久的に保持するには、レスポンスに LANGUAGE_COOKIE_NAME クッキーを設定します。
from django.conf import settings\nfrom django.http import HttpResponse\nfrom django.utils import translation\n\nuser_language = "fr"\ntranslation.activate(user_language)\nresponse = HttpResponse(...)\nresponse.set_cookie(settings.LANGUAGE_COOKIE_NAME, user_language)\n通常、両方を使う必要があるでしょう: django.utils.translation.activate() はこのスレッドに対して言語を変更します。そして、クッキーをセットするとこの設定が将来のリクエストに恒久的に反映されます。
Django はビューやテンプレートで使うための豊富な国際化ツールセットを提供していますが、Django 固有のコードに使い方を限定しているわけではありません。Django の翻訳システムを使えば、任意のテキストを Django がサポートしている任意の言語に翻訳できます (もちろん、適切な翻訳カタログが存在する場合に限ります)。翻訳カタログを読み込んで有効にし、テキストを好きな言語に翻訳することも可能ですが、元の言語に戻すことを忘れないでください。翻訳カタログの有効化はスレッド単位で行われ、そのような変更は同じスレッドで実行されているコードに影響するからです。
\n例:
\nfrom django.utils import translation\n\n\ndef welcome_translated(language):\n cur_language = translation.get_language()\n try:\n translation.activate(language)\n text = translation.gettext("welcome")\n finally:\n translation.activate(cur_language)\n return text\nこの関数を 'de' という値で呼び出すと、 LANGUAGE_CODE やミドルウェアで設定されている言語に関係なく、 "Willkommen" が返されます。
特に注目すべき関数は、現在のスレッドで使われている言語を返す django.utils.translation.get_language() 、現在のスレッドの翻訳カタログを有効にする django.utils.translation.activate() 、与えられた言語が Django でサポートされているかどうかをチェックする django.utils.translation.check_for_language() です。
より簡潔なコードを書くために、コンテキストマネージャ django.utils.translation.override() も用意されています、これは実行時に現在の言語を保存し、終了時にそれを復元します。これを使うと、上の例は次のようになります:
from django.utils import translation\n\n\ndef welcome_translated(language):\n with translation.override(language):\n return translation.gettext("welcome")\nDjango の翻訳システムは Python に付属している標準の gettext モジュールを使います。 gettext を知っていれば、Django が翻訳を行う方法について、以下のような特徴があることに気づくかもしれません:
文字列ドメインは django または djangojs です。この文字列ドメインは、共通のメッセージファイルライブラリ (通常は /usr/share/locale/) にデータを保存する異なるプログラムを区別するために使用されます。 django ドメインは Python とテンプレートの翻訳文字列に使われ、グローバル翻訳カタログに読み込まれます。 djangojs ドメインはできるだけ小さくなるように、 JavaScript の翻訳カタログにだけ使われます。
Django は xgettext だけを使っているわけではありません。これは xgettext と msgfmt を Python でラップしたものです。これは主に利便性のためです。
翻訳を準備したら、あるいは Django に付属している翻訳を使いたい場合は、アプリの設定で翻訳を有効にする必要があります。
\nDjangoは、インストール全体、特定のユーザー、またはその両方に対して、使用する言語を決定する非常に柔軟なモデルを持っています。
\nインストール全体の優先言語を設定するには、 LANGUAGE_CODE を設定してください。Django はこの言語をデフォルトの翻訳として使います。ロケールミドルウェアが採用するメソッド (下記参照) を使って、より適切な翻訳が見つからなかった場合の最終的な翻訳です。
Django を母国語で動かしたいだけなら、 LANGUAGE_CODE を設定し、対応する メッセージファイル とそのコンパイルバージョン (.mo) が存在することを確認するだけです。
各ユーザに好きな言語を指定させたい場合は、 LocaleMiddleware を使用する必要があります。ロケール ミドルウェア LocaleMiddleware はリクエストのデータに基づいて言語を選択できるようにします。これは各ユーザのためにコンテンツをカスタマイズします。
LocaleMiddleware を使うには、django.middleware.locale.LocaleMiddleware' を MIDDLEWARE 設定に追加します。ミドルウェアの順番は重要なので、以下のガイドラインに従ってください:
最初にインストールされるミドルウェアの1つであることを確認してください。
なぜなら LocaleMiddleware はセッションデータを利用するからです。また、 CommonMiddleware はリクエストされたURLを解決するために有効な言語を必要とするので、 CommonMiddleware の前に来る必要があります。
CacheMiddleware を使用する場合は、その後ろに LocaleMiddleware を記述してください。
たとえば、MIDDLEWARE は次のようになります:
MIDDLEWARE = [\n "django.contrib.sessions.middleware.SessionMiddleware",\n "django.middleware.locale.LocaleMiddleware",\n "django.middleware.common.CommonMiddleware",\n]\n(ミドルウェアについては ミドルウェアのドキュメント を参照してください)。
\nLocaleMiddleware は以下のアルゴリズムに従ってユーザーの言語設定を決定しようとします:
最初に、リクエストされたURLの言語プレフィックスを探します。 これはルートの URLconf で i18n_patterns 関数を使用している場合にだけ実行されます。言語プレフィックスとURLパターンの国際化方法についての詳細は 国際化: URL パターン内 を参照してください。
それに失敗すれば、クッキーを探します。
\n使用されるクッキーの名前は LANGUAGE_COOKIE_NAME 設定によって設定されます。(デフォルトの名前は django_language です)。
それに失敗した場合は Accept-Language HTTPヘッダを調べます。このヘッダはブラウザから送られ、サーバにどの言語を優先するのかを伝えます。Django は、翻訳可能な言語が見つかるまで、ヘッダの各言語を試します。
それに失敗すると、グローバルな LANGUAGE_CODE 設定を使用します。
メモ:
\nこれらの場所では、言語設定は標準の 言語コード 文字列で指定します。たとえば、ブラジルポルトガル語は pt-br です。
ベース言語が利用可能で、指定されたサブ言語が利用できない場合、 Django はベース言語を使います。たとえば、ユーザが de-at (オーストリアのドイツ語) を指定したが、 Django には de しかない場合、 Django は de を使います。
選択できるのは LANGUAGES 設定にリストされている言語だけです。言語選択を提供されている言語のサブセットに制限したい場合(アプリケーションがすべての言語を提供していないため)、 LANGUAGES に言語のリストを設定します。たとえば、次のようにします：
LANGUAGES = [\n ("de", _("German")),\n ("en", _("English")),\n]\nこの例では、自動選択できる言語をドイツ語と英語（および de-ch や en-us のようなサブ言語）に制限しています。
前の箇所で説明したように、カスタムの LANGUAGES 設定を定義すれば、言語名を翻訳文字列としてマークできます。ただし、循環インポートを避けるために、 gettext() の代わりに gettext_lazy() を使ってください。
以下はサンプルの設定ファイルです:
\nfrom django.utils.translation import gettext_lazy as _\n\nLANGUAGES = [\n ("de", _("German")),\n ("en", _("English")),\n]\nLocaleMiddleware がユーザの設定を決定すると、その設定を HttpRequest の request.LANGUAGE_CODE として利用できるようにします。この値はビューのコードで自由に読み込むことができます。以下に例を示します:
from django.http import HttpResponse\n\n\ndef hello_world(request, count):\n if request.LANGUAGE_CODE == "de-at":\n return HttpResponse("You prefer to read Austrian German.")\n else:\n return HttpResponse("You prefer to read another language.")\n静的な(ミドルウェアを使わない)翻訳では、言語は settings.LANGUAGE_CODE にあり、動的な(ミドルウェアを使った)翻訳では request.LANGUAGE_CODE にあることに注意してください。
実行時に、 Django はリテラルと翻訳の統合カタログをメモリ内に構築します。これを実現するために、コンパイルされた メッセージファイル (.mo) を読み込むために異なるファイルパスを調べる順序と、同じリテラルに対して複数の翻訳がある場合の優先順位について、以下のアルゴリズムに従って翻訳を探します:
LOCALE_PATHS に列挙されているディレクトリが最も優先され、最初に記述されているものが後に記述されているものよりも優先されます。
次に、 INSTALLED_APPS に列挙されている各インストール済みアプリの locale ディレクトリを探し、存在すればそれを使用します。 このとき、最初に指定されたものが後に指定されたものよりも優先されます。
最後に、 django/conf/locale にある Django が提供する基本翻訳がフォールバックとして使われます。
すべての場合において、翻訳を含むディレクトリの名前は locale name 表記で指定します。例えば de、pt_BR、es_AR などです。地域言語バリアントの未翻訳の文字列は一般言語の翻訳を使用します。たとえば、未翻訳の pt_BR 文字列は pt の翻訳を使用します。
こうすることで、独自の翻訳を含むアプリケーションを書くことができ、プロジェクトでベースとなる翻訳を上書きできます。あるいは、いくつかのアプリから大きなプロジェクトを作り、すべての翻訳を、作成中のプロジェクトに特化した1つの大きな共通メッセージファイルにまとめることもできます。選択肢はあなたの自由です。
\nメッセージ・ファイルのリポジトリはすべて同じ構造になっています。それらは下記のようなものです:
\n設定ファイルの LOCALE_PATHS にリストされているすべてのパスは、<language>/LC_MESSAGES/django.(po|mo) で検索されます。
$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)
$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)
メッセージファイルを作成するには django-admin makemessages ツールを使用します。また、 django-admin compilemessages を使って、 gettext が使用するバイナリファイル .mo を作成します。
また、 django-admin compilemessages --settings=path.to.settings を実行すると、コンパイラが LOCALE_PATHS 設定にあるすべてのディレクトリを処理するようになります。
Django は、翻訳可能なプロジェクト内の元の文字列は英語で書かれているという一般的な前提に立っています。他の言語を選ぶこともできますが、ある制限に注意する必要があります:
\ngettext はオリジナルのメッセージに対して2つの複数形しか提供しないので、もしベース言語の複数形のルールが英語と異なる場合は、すべての複数形を含むようにベース言語の翻訳も提供する必要があります。
英語のバージョンが有効になっていて、英語の文字列がない場合、フォールバック言語はプロジェクトの LANGUAGE_CODE ではなく、オリジナルの文字列になります。たとえば、LANGUAGE_CODE がスペイン語に設定されていて、元の文字列がロシア語で書かれているサイトを訪れた英語のユーザは、スペイン語ではなくロシア語のテキストを見ることになります。