---
title: "翻訳"
version: 5.2
locale: ja
source: https://docs.djangoproject.com/ja/5.2/topics/i18n/translation/
canonical: https://djangodocs.dev/ja/5.2/topics/i18n/translation/
---
# 翻訳
## 概要
Django プロジェクトを翻訳可能にするためには、Python コードやテンプレートに、多少のフックを加筆しなければなりません。このフックは [翻訳文字列](/ja/5.2/topics/i18n/#term-translation-string) と呼ばれます。翻訳文字列は Django に「このテキストに対する翻訳が有効な場合、このテキストはエンドユーザの言語に翻訳すべきだ」ということを通知します。翻訳可能な文字列をマークすることは開発者の責任です。システムが翻訳できるのは指定された文字列だけなのです。
Django は、翻訳文字列を [メッセージファイル](/ja/5.2/topics/i18n/#term-message-file) に抽出するユーティリティを提供します。このファイルがあるため、翻訳者が対象の言語において翻訳文字列に対応する文字列を用意することが簡単になります。翻訳者がメッセージファイルの中身を書き終わったら、それをコンパイルしなければなりません。このプロセスは GNU gettext ツー ルキットに依存しています。
これが済めば、 Django はユーザの言語設定に従って、オンザフライでアプリケーションを利用可能な言語に翻訳するようになります。
Django の国際化フックはデフォルトで有効になっており、これは、フレームワークの特定の箇所で i18n に関する小さなオーバーヘッドが発生することを意味します。国際化を使わない場合は、 [`USE_I18N = False`](/ja/5.2/ref/settings/#std-setting-USE_I18N) を設定ファイルに記述してください。そうすれば Django は国際化の部品を読み込まないようにして多少の最適化をします。
> **Note**
>
> プロジェクトで翻訳機能が有効になっていることを確認してください (最も早いのは、 [`MIDDLEWARE`](/ja/5.2/ref/settings/#std-setting-MIDDLEWARE) が [`django.middleware.locale.LocaleMiddleware`](/ja/5.2/ref/middleware/#django.middleware.locale.LocaleMiddleware) を含むかどうかチェックすることです) 。まだの場合は、[Django はどうやって言語の優先順位を検出するのか？](#how-django-discovers-language-preference) を参照してください。
## Python コードでの国際化
### 標準的な翻訳
翻訳対象の文字列を関数 [`gettext()`](/ja/5.2/ref/utils/#django.utils.translation.gettext) で指定します。入力の手間を省くため、この関数は短い別名 `_` としてインポートするのが慣例です。
> **Note**
>
> Python の標準ライブラリ `gettext` モジュールは、グローバルの名前空間に `_()` という名前で `gettext()` をインストールします。 Django ではこの方法に従っていませんが、それは以下の理由からです:
>
> 1. 特定のファイルのデフォルトの翻訳メソッドとして [`gettext_lazy()`](/ja/5.2/ref/utils/#django.utils.translation.gettext_lazy) を使うべき場合もあります。グローバル名前空間に `_()` がないと、開発者はどれが最も適切な翻訳関数かを考えなければなりません。
> 2. アンダースコア文字 (`_`) は、 Python の対話シェルや doctest で書かれたテストの中では「直前の式の値」を表します。そのため、グローバル名前空間に `_()` をインストールすると、干渉して問題を引き起こします。 `gettext()` を `_()` という名前で明示的に import すれば、この問題を回避できます。
> **_ として別名をつけられる関数は？**
>
> ([`makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) で使われる) `xgettext` が動作する方法のせいで、単一の文字列引数を持つ関数のみが `_` として import できます。
>
> - [`gettext()`](/ja/5.2/ref/utils/#django.utils.translation.gettext)
> - [`gettext_lazy()`](/ja/5.2/ref/utils/#django.utils.translation.gettext_lazy)
この例では、`"Welcome to my site."` というテキストが翻訳文字列としてマークされています:
```
from django.http import HttpResponse
from django.utils.translation import gettext as _
def my_view(request):
output = _("Welcome to my site.")
return HttpResponse(output)
```
別名を付けなくても同じコードを書くことができます。次の例は、上の例とまったく同一です:
```
from django.http import HttpResponse
from django.utils.translation import gettext
def my_view(request):
output = gettext("Welcome to my site.")
return HttpResponse(output)
```
翻訳は、計算済みの値に適用されます。次の例は、上の2つの例とまったく同一です:
```
def my_view(request):
words = ["Welcome", "to", "my", "site."]
output = _(" ".join(words))
return HttpResponse(output)
```
翻訳は変数にも適用されます。次の例もまた、上の例とまったく同一です:
```
def my_view(request):
sentence = "Welcome to my site."
output = _(sentence)
return HttpResponse(output)
```
(上の 2 つの例のように変数や計算済みの値を使う場合の注意点として、Django の翻訳文字列検出ユーティリティ [`django-admin makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) はこれらの文字列を検出できません。詳しくは後の [`makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) の節で説明します。)
`_()` や `gettext()` に渡す文字列には、Pyton の標準の名前付き補完構文によるプレースホルダを使えます。例えば:
```
def my_view(request, m, d):
output = _("Today is %(month)s %(day)s.") % {"month": m, "day": d}
return HttpResponse(output)
```
このテクニックを使うと、言語ごとの翻訳でプレースホルダを並び替えられるようになります。例えば、英語の翻訳文 `"Today is Nobember, 26."` に対して、スペイン語では `"Hoy es 26 de noviembre."` となるように、月と日のプレースホルダの位置を入れ替えることができます。
この理由から、引数が複数ある場合には、固定引数を使った補完 (`%s` や `%d`) ではなく、名前付きの補完 (`%(day)s`) を使ってください。固定引数による補完を使った場合、プレースホルダを正しい順番で翻訳できない場合があります。
文字列の抽出は `xgettext` コマンドによって行われるため、Django でサポートされる構文も `gettext` が対応しているものに限られます。Python の [f文字列](https://docs.python.org/3/reference/lexical_analysis.html#f-strings) は `gettext` 関数と直接組み合わせて使うことはできません。なぜなら、f文字列の式は `gettext` に渡される前に評価されてしまうからです。つまり、 `_(f"Welcome {name}")` のように書いても、翻訳の前に変数が展開されてしまうため、期待どおりには動作しません。代わりに、名前付き文字列補間を使用してください：
```
# Good
_("Welcome %(name)s") % {"name": name}
# Good
_("Welcome {name}").format(name=name)
# Bad
_(f"Welcome {name}") # f-string evaluated before translation.
```
JavaScript のテンプレート文字列を使うには、 `gettext` のバージョン 0.21 以降が必要です。
### 翻訳者へのコメント
翻訳可能な文字列についてのヒントを翻訳者に示したい場合、文字列の直前の行で `Translators` キーワードでプレフィックスされたコメントを追加できます。例えば:
```
def my_view(request):
# Translators: This message appears on the home page only
output = gettext("Welcome to my site.")
```
コメントは、後に記述された翻訳可能な文章に関連付けられた、結果の `.po` ファイル内に表示され、ほとんどの翻訳ツールで表示されます。
> **Note**
>
> 完全を期すために示すと、以下が結果として生成される対応する `.po` ファイルの断片です。
>
> ```po
> #. Translators: This message appears on the home page only
> # path/to/python/file.py:123
> msgid "Welcome to my site."
> msgstr ""
> ```
これはテンプレート内でも動作します。詳しくは [テンプレートにおける翻訳者のためのコメント](#translator-comments-in-templates) を参照してください。
### no-op (何もしない) として文字列をマークする
翻訳しない文字列としてマークするためには、[`django.utils.translation.gettext_noop()`](/ja/5.2/ref/utils/#django.utils.translation.gettext_noop) を使ってください。文字列は、変数より後で翻訳されます。
ソース言語内に保持すべき構成文字列がある場合、これを使ってください。これは、システムやユーザー (たとえばデータベース内の文字列) を介して交換される一方で、最後の時点 (たとえばユーザに文字列が表示されるとき) で翻訳される必要があるからです。
### 複数形
複数形のメッセージを指定するには、関数 [`django.utils.translation.ngettext()`](/ja/5.2/ref/utils/#django.utils.translation.ngettext) を使ってください。
`ngettext` は 3 つの引数を取ります: 単数形の文字列、複数形の文字列、オブジェクトの数です。
この関数は、Django アプリケーションを数と [複数形](https://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms) の複雑さが英語で 2 より大きい (その値にかかわらず、単数には 'object'、そして `count` が 1 ではない全ての場合に 'objects' となります。) 言語にローカライズさせる必要がある場合に役立ちます。
例:
```
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)
```
この例では、オブジェクトの数値は `count` 変数として翻訳言語に渡されます。
複数形は、複雑で言語によって異なる動作をすることに注意してください。`count` と 1 の比較は正しいルールではないことがあります。以下のコードは洗練されて見えますが、いくつかの言語に対しては誤った結果を生み出します:
```
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}
```
あなた自身の単数複数ロジックを実装しないでください。おそらく正しくなりません。このようなケースでは、以下のようなコードを考えてみてください。
```
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,
}
```
> **Note**
>
> `ngettext()` を使うときは、リテラルで挿入される全ての変数に対して単一の名前を使うようにしてください。以下の例で、2 つの翻訳文字列でどのように `name` Python 変数が使われるかに注意してください。この例は、上述した通りいくつかの言語で間違っている以外に、失敗するでしょう:
>
> ```
> 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,
> }
> ```
>
> [`django-admin compilemessages`](/ja/5.2/ref/django-admin/#django-admin-compilemessages) を実行すると、以下のエラーが発生するでしょう。
>
> ```pytb
> a format specification for argument 'name', as in 'msgstr[0]', doesn't exist in 'msgid'
> ```
### 文脈マーカー
単語は複数の意味を持っている場合があります。例えば、英語の `"May"` は、月名と動詞を指します。翻訳者が異なる文脈でこれらの単語を正しく翻訳できるようにするには、[`django.utils.translation.pgettext()`](/ja/5.2/ref/utils/#django.utils.translation.pgettext) 関数、もしくは文字列が複数形を必要とする場合は [`django.utils.translation.npgettext()`](/ja/5.2/ref/utils/#django.utils.translation.npgettext) 関数を使うことができます。両方とも、第 1 変数として文脈文字列を取ります。
結果の `.po` ファイルで、文字列は同じ文字列に対する異なる文脈マーカーがあるのと同じ頻度で出現し (コンテキストは `msgctxt` 行に出現します)、これらそれぞれに対して翻訳者が異なる翻訳ができるようにします。
例:
```
from django.utils.translation import pgettext
month = pgettext("month name", "May")
```
もしくは:
```
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")
)
```
これは `.po` ファイル内に以下のように出現します:
```po
msgctxt "month name"
msgid "May"
msgstr ""
```
文脈マーカーは、[`translate`](#std-templatetag-translate) と [`blocktranslate`](#std-templatetag-blocktranslate) テンプレートタグによってもサポートされています。
### 遅延 (Lazy な) 翻訳
Lazy に、つまり遅延的に、値が呼ばれたときではなくアクセスされたときに文字列を翻訳するためには、[`django.utils.translation`](/ja/5.2/ref/utils/#module-django.utils.translation) (名前の `lazy` 接尾辞ですぐ分かります) の翻訳関数の lazy バージョンを使ってください、
これらの関数は、Lazy な文字列参照を保持します -- 実際の翻訳ではありません。翻訳自体はテンプレートレンダリング内のように、文字列が文字列コンテキスト内で使われるときに行われます。
これらの関数への呼び出しがモジュールのロード時に実行されるコードパスにある場合は、これは不可欠です。
これは、モデル、フォーム、モデルフォームを定義するときに簡単に発生することができるものです。これは、Django がフィールドを実際にクラスレベルの属性にするように実装するためです。 そのため、以下のような場合は lazy な翻訳を使用してください:
#### モデルフィールドとリレーションシップの `verbose_name` と `help_text` オプションの値
例えば、以下のモデルの *name* フィールドのヘルプテキストを翻訳するためには、以下のようにします:
```
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"))
```
[`verbose_name`](/ja/5.2/ref/models/options/#django.db.models.Options.verbose_name) オプションを使えば、[`ForeignKey`](/ja/5.2/ref/models/fields/#django.db.models.ForeignKey)、[`ManyToManyField`](/ja/5.2/ref/models/fields/#django.db.models.ManyToManyField) や [`OneToOneField`](/ja/5.2/ref/models/fields/#django.db.models.OneToOneField) リレーションシップの名前を翻訳可能にできます:
```
class MyThing(models.Model):
kind = models.ForeignKey(
ThingKind,
on_delete=models.CASCADE,
related_name="kinds",
verbose_name=_("kind"),
)
```
[`verbose_name`](/ja/5.2/ref/models/options/#django.db.models.Options.verbose_name) と同様に、必要に応じて Django が自動的にタイトルケースに直すので、リレーションシップに対する小文字の冗長な名前テキストを提供する必要があります。
#### モデルの冗長な名前の値
フォールバックの英語中心とモデルのクラス名を見ることによって Django が動作する冗長な名前の純粋な決定に頼るよりも、明示的な [`verbose_name`](/ja/5.2/ref/models/options/#django.db.models.Options.verbose_name) と [`verbose_name_plural`](/ja/5.2/ref/models/options/#django.db.models.Options.verbose_name_plural) オプションを指定することが推奨されます:
```
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")
```
#### モデルメソッド `description` を `@display` デコレーターに渡す。
モデルメソッドに対しては、[`display()`](/ja/5.2/ref/contrib/admin/#django.contrib.admin.display) デコレータの `short_description` 引数で Djangoと admin サイトへの翻訳が提供できます。
```
from django.contrib import admin
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"),
)
@admin.display(description=_("Is it a mouse?"))
def is_mouse(self):
return self.kind.type == MOUSE_TYPE
```
### 遅延 (Lazyな) 翻訳オブジェクトの使用方法
`gettext_lazy()` 呼び出しの結果は、他の Django コード内で文字列 ([`str`](https://docs.python.org/3/library/stdtypes.html#str) オブジェクト) を使うときはいつでも使うことができますが、気まぐれな Python コードでうまく動作しないかもしれません。例えば、[requests](https://pypi.org/project/requests/) ライブラリが `gettext_lazy` オブジェクトを処理しないので、以下は動作しません:
```
body = gettext_lazy("I \u2764 Django") # (Unicode :heart:)
requests.post("https://example.com/send", data={"body": body})
```
`gettext_lazy()` オブジェクトを非 Django コードに渡す前にテキスト文字列にキャストすることで、この問題を防ぐことができます:
```
requests.post("https://example.com/send", data={"body": str(body)})
```
`gettext_lazy` という長い名前を使いたくない場合は、次のように `_` (アンダースコア) としてエイリアスできます。
```
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"))
```
モデルやユーティリティ関数内で文字列に `gettext_lazy()` や `ngettext_lazy()` を使用してマークすることはよく行われます。これらのオブジェクトをコードの他の場所で扱う際には、誤って文字列に変換しないよう注意する必要があります。なぜなら、これらの変換は可能な限り遅延されるべきだからです（正しいロケールが効果を発揮するため）。これには、次に説明するヘルパー関数の使用が必要です。
#### 遅延翻訳と複数形
複数の文字列に対して遅延翻訳 (`n[p]gettext_lazy`) を使用する場合、一般的に文字列を定義する時点では `number` 引数を知りません。そのため、 `number` 引数に整数ではなくキー名を渡すことが許可されています。そうすると、文字列の補間時に `number` がそのキーの辞書で検索されます。以下に例を示します:
```
from django import forms
from django.core.exceptions import ValidationError
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 ValidationError(self.error_message % {"num": number})
```
文字列の中に名前のないプレースホルダが1つだけ含まれている場合は、 `number` 引数で直接補間できます:
```
class MyForm(forms.Form):
error_message = ngettext_lazy(
"You provided %d argument",
"You provided %d arguments",
)
def clean(self):
# ...
if error:
raise ValidationError(self.error_message % number)
```
#### 文字列のフォーマット: `format_lazy()`
Python の [`str.format()`](https://docs.python.org/3/library/stdtypes.html#str.format) メソッドは `format_string` や [`str.format()`](https://docs.python.org/3/library/stdtypes.html#str.format) の引数に遅延 (lazy) 翻訳オブジェクトが含まれている場合には動作しません。その代わりに [`django.utils.text.format_lazy()`](/ja/5.2/ref/utils/#django.utils.text.format_lazy) を使うことができます。これは結果が文字列に含まれるときだけ `str.format()` メソッドを実行する遅延オブジェクトを作成します。たとえば、次のようになります:
```
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)
```
この場合、 `result` 内の遅延翻訳は、 `result` 自体が文字列で使用されるとき（通常はテンプレートのレンダリング時）にだけ文字列に変換されます。
#### その他の遅延翻訳の使い方
翻訳を遅らせたいが、翻訳可能な文字列を別の関数の引数として渡さなければならない場合、この関数を遅延 (Lazy) 呼び出しでラップできます。たとえば次のようにします:
```
from django.utils.functional import lazy
from django.utils.translation import gettext_lazy as _
def to_lower(string):
return string.lower()
to_lower_lazy = lazy(to_lower, str)
```
その後、次のようにします:
```
lazy_string = to_lower_lazy(_("My STRING!"))
```
### 言語のローカライズされた名前
#### `get_language_info(lang_code)`
`get_language_info()` 関数は、言語について詳細な情報を提供します:
```pycon
>>> 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
```
ディクショナリの `name`、`name_local`、`name_translated` 属性は、言語の英語名、言語自体、カレントのアクティブ言語をそれぞれ含んでいます。`bidi` 属性は双方向性の言語に対してのみ True です。
言語情報のソースは `django.conf.locale` モジュールです。テンプレートコードでも、この情報に対して同じようにアクセスできます。以下を参照してください。
## 国際化: テンプレート内
[Django テンプレート](/ja/5.2/ref/templates/language/) 内での翻訳は 2 つのテンプレートタグと Pthon コードとはやや異なるシンタックスを使います。テンプレートでこれらのタグを使えるようにするには、`{% load i18n %}` をテンプレートの先頭に対して設置してください。全てのテンプレートタグと同じように、すでに `i18n` をロードしているテンプレートを extend している場合であっても、翻訳を使用する全てのテンプレートでロードする必要があります。
> **Warning**
>
> 翻訳された文字列はテンプレートでレンダリングされるときにエスケープされません。これにより、たとえば強調のために HTML を翻訳に含めることができますが、潜在的に危険な文字 (`"` など) も変更されずにレンダリングされます。
### `translate` テンプレートタグ
`{% translate %}` テンプレートタグは、(シングルクオートやダブルクオートで囲まれた) 定数文字列や変数コンテンツを翻訳します:
```html+django
{% translate "This is the title." %}
{% translate myvar %}
```
`noop` オプションが存在する場合、変数はそのままですが翻訳の対象外となります。将来的に翻訳を必要とするコンテンツを "もみ消している" ときに役立ちます:
```html+django
{% translate "myvar" noop %}
```
内部的には、インラインの翻訳は [`gettext()`](/ja/5.2/ref/utils/#django.utils.translation.gettext) 呼び出しを使っています。
テンプレート var (上記の `myvar`) がタグに渡された場合、最初にランタイムで変数から文字列へと解決し、それからメッセージカタログ内でその文字列をルックアップします。
`{% translate %}` 内の文字列でテンプレート変数を混ぜることはできません。翻訳が変数 (プレースホルダ) とともに文字列を必要とする場合は、代わりに [`{% blocktranslate %}`](#std-templatetag-blocktranslate) を使ってください。
翻訳された文字列を表示させずに取り出したい場合は、以下の構文が使用できます:
```html+django
{% translate "This is the title" as the_title %}
{{ the_title }}
```
実際には、テンプレート内の複数の場所で使用できる文字列を取得したり、他のテンプレートタグやフィルタリングするための引数として出力を使用したりする目的でこれを使うことになるでしょう:
```html+django
{% translate "starting point" as start %}
{% translate "end point" as end %}
{% translate "La Grande Boucle" as race %}
{% for stage in tour_stages %}
{% cycle start end %}: {{ stage }}{% if forloop.counter|divisibleby:2 %}
{% else %}, {% endif %}
{% endfor %}
```
`{% translate %}` は、`context` キーワードを使う [文脈マーカー](#contextual-markers) もサポートしています:
```html+django
{% translate "May" context "month name" %}
```
### `blocktranslate` テンプレートタグ
[`translate`](#std-templatetag-translate) タグとは対照的に、 `blocktranslate` タグはプレースホルダーを使うことで、リテラルその他の内容からなる複雑な文章を翻訳できます:
```html+django
{% blocktranslate %}This string will have {{ value }} inside.{% endblocktranslate %}
```
オブジェクトの `object` 属性にアクセスしたり、テンプレートフィルタを使ったりといったテンプレート式を翻訳するには、その式を翻訳ブロック内で使うローカル変数に結びつける必要があります。たとえば、次のようにします:
```html+django
{% blocktranslate with amount=article.price %}
That will cost $ {{ amount }}.
{% endblocktranslate %}
{% blocktranslate with myvar=value|filter %}
This will have {{ myvar }} inside.
{% endblocktranslate %}
```
単一の `blocktranslate` タグ内で複数の式を使うこともできます:
```html+django
{% blocktranslate with book_t=book|title author_t=author|title %}
This is {{ book_t }} by {{ author_t }}
{% endblocktranslate %}
```
> **Note**
>
> 次のような、冗長な古い書式もまだサポートされています: `{% blocktranslate with book|title as book_t and author|title as author_t %}`
他のブロックタグ (例えば [`{% for %}`](/ja/5.2/ref/templates/builtins/#std-templatetag-for) や [`{% if %}`](/ja/5.2/ref/templates/builtins/#std-templatetag-if)) は `blocktranslate` タグの中では使えません。
ブロック引数の解決に失敗した場合、 `blocktranslate` は [`deactivate_all()`](/ja/5.2/ref/utils/#django.utils.translation.deactivate_all) 関数を用いて、現在アクティブな言語を一時的に非アクティブにすることで、デフォルトの言語にフォールバックします。
このタグは複数形にも対応しています。使用するには:
- カウンタの値を `count` という名前で指定し結び付けます。この値は正しい複数形の選択に使用されます。
- `{% blocktranslate %}` と `{% endblocktranslate %}` のタグの中で単数形と複数形を `{% plural %}` タグで区切って指定してください。
例:
```html+django
{% blocktranslate count counter=list|length %}
There is {{ counter }} {{ name }} object.
{% plural %}
There are {{ counter }} {{ name }} objects.
{% endblocktranslate %}
```
より複雑な例:
```html+django
{% blocktranslate with amount=article.price count years=i.length %}
That will cost $ {{ amount }} per year.
{% plural %}
That will cost $ {{ amount }} per {{ years }} years.
{% endblocktranslate %}
```
カウンターの値の追加に複数化機能とローカル変数への値のバインドの両方を使用する場合、 `blocktranslate` 構文は内部的に `ngettext` 呼び出しに変換されることに注意してください。つまり、 [ngettext 変数に関する注意事項](#pluralization-var-notes) と同じことに気を付ける必要があります。
URLの逆引きは `blocktranslate` 内では行えないので、事前に取得（保存）しておく必要があります:
```html+django
{% url 'path.to.view' arg arg2 as the_url %}
{% blocktranslate %}
This is a URL: {{ the_url }}
{% endblocktranslate %}
```
翻訳された文字列を表示させずに取り出したい場合は、以下の構文が使用できます:
```html+django
{% blocktranslate asvar the_title %}The title is {{ title }}.{% endblocktranslate %}
{{ the_title }}
```
実際には、テンプレート内の複数の場所で使用できる文字列を取得したり、他のテンプレートタグやフィルタリングするための引数として出力を使用したりする目的でこれを使うことになるでしょう:
`{% blocktranslate %}` は、`context` キーワードを使う [文脈マーカー](#contextual-markers) もサポートしています:
```html+django
{% blocktranslate with name=user.username context "greeting" %}Hi {{ name }}{% endblocktranslate %}
```
`{% blocktranslate %}` タグのもう1つの機能は、`trimmed` オプションです。このオプションは、`{% blocktranslate %}` タグのコンテンツの先頭と末尾から改行文字を削除し、行の先頭と末尾の空白を置き換え、すべての行を空白文字で区切って1行に結合します。これは、`{% blocktranslate %}` タグのコンテンツをインデントしても、インデント文字が対応する `.po` ファイルのエントリに含まれないようにするのに非常に便利で、翻訳作業が簡単になります。
例えば、次の `{% blocktranslate %}` タグ:
```html+django
{% blocktranslate trimmed %}
First sentence.
Second paragraph.
{% endblocktranslate %}
```
の出力結果は `.po` ファイル内では `"First sentence. Second paragraph."` となります。対照に、 `trimmed` オプションが指定されていない場合は `"\n First sentence.\n Second paragraph.\n"` となります。
### タグとフィルタに渡される文字列リテラル
タグやフィルタの引数として渡された文字列リテラルは、見慣れた `_()` 構文を使って翻訳できます:
```html+django
{% some_tag _("Page not found") value|yesno:_("yes,no") %}
```
この場合、タグもフィルタも翻訳された文字列を見るので、翻訳を意識する必要はありません。
> **Note**
>
> この例では、個々の文字列 `"yes"` と `"no"` ではなく、`"yes,no"` という文字列が翻訳基盤に渡されます。翻訳された文字列は、フィルタをパースするコードが引数をどう分割するかを知るために、カンマを含む必要があります。たとえば、ドイツ語の翻訳者は文字列 `"yes,no"` を `"ja,nein"` (カンマはそのまま) と翻訳するでしょう。
### テンプレートにおける翻訳者のためのコメント
[Pythonコード](#translator-comments) の場合と同様に、これらの翻訳者向けのメモはコメントを使用して指定できます。[`comment`](/ja/5.2/ref/templates/builtins/#std-templatetag-comment) タグを使用する場合がその一例です：
```html+django
{% comment %}Translators: View verb{% endcomment %}
{% translate "View" %}
{% comment %}Translators: Short intro blurb{% endcomment %}
{% blocktranslate %}A multiline translatable
literal.{% endblocktranslate %}
```
または [一行コメント構文](/ja/5.2/ref/templates/language/#template-comments) `{#` ... ... `#}` で:
```html+django
{# Translators: Label of a button that triggers search #}
{# Translators: This is a text of the base template #}
{% blocktranslate %}Ambiguous translatable block of text{% endblocktranslate %}
```
> **Note**
>
> 完全を期すために示すと、以下が結果として生成される対応する `.po` ファイルの断片です。:
>
> ```po
> #. 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 ""
> ```
### テンプレートで言語を切り替える
テンプレートの中で言語を選択したい場合、 `language` テンプレートタグが使用できます:
```html+django
{% load i18n %}
{% get_current_language as LANGUAGE_CODE %}
{% translate "Welcome to our page" %}
{% language 'en' %}
{% get_current_language as LANGUAGE_CODE %}
{% translate "Welcome to our page" %}
{% endlanguage %}
```
"Welcome to our page" は、1つめのコードでは現在の言語を使って表示されますが、2つめのコードでは常に英語になります。
### その他のタグ
これらのタグには同時に `{% load i18n %}` が必要です。
#### `get_available_languages`
`{% get_available_languages as LANGUAGES %}` はタプルのリストを返します。最初の要素は言語コード [language code](/ja/5.2/topics/i18n/#term-language-code) で、2番目の要素は言語名 (現在アクティブなロケールに翻訳されたもの) です。
#### `get_current_language`
`{% get_current_language as LANGUAGE_CODE %}` は現在のユーザの優先言語を文字列として返します。たとえば `en-us` です。 [Django はどうやって言語の優先順位を検出するのか？](#how-django-discovers-language-preference) を参照してください。
#### `get_current_language_bidi`
`{% get_current_language_bidi as LANGUAGE_BIDI %}` は現在のロケールの文章を書く方向を返します。もし `True` なら、ヘブライ語やアラビア語などの右から左へ書く言語です。もし `False` なら、英語、フランス語、ドイツ語などの左から右へ書く言語です。
#### `i18n` コンテキストプロセッサ
もし [`django.template.context_processors.i18n`](/ja/5.2/ref/templates/api/#django.template.context_processors.i18n) コンテキストプロセッサを有効にすると、各 `RequestContext` は上で定義した `LANGUAGES`, `LANGUAGE_CODE`, `LANGUAGE_BIDI` にアクセスできるようになります。
#### `get_language_info`
また、提供されているテンプレートタグとフィルタを使えば、利用可能な言語の情報を取得することもできます。一つの言語に関する情報を取得するには `{% get_language_info %}` タグを使います:
```html+django
{% get_language_info for LANGUAGE_CODE as lang %}
{% get_language_info for "pl" as lang %}
```
その後、下記のように情報にアクセスできます:
```html+django
Language code: {{ lang.code }}
Name of language: {{ lang.name_local }}
Name in English: {{ lang.name }}
Bi-directional: {{ lang.bidi }}
Name in the active language: {{ lang.name_translated }}
```
#### `get_language_info_list`
また、`{% get_language_info_list %}` のテンプレートタグを使えば、言語のリスト(例えば [`LANGUAGES`](/ja/5.2/ref/settings/#std-setting-LANGUAGES) で指定されたアクティブな言語)の情報を取得できます。`{% get_language_info_list %}` を使って言語セレクタを表示する方法の例は [set\_language リダイレクトビューのセクション](#set-language-redirect-view) を参照してください。
[`LANGUAGES`](/ja/5.2/ref/settings/#std-setting-LANGUAGES) 形式のタプルのリストに加え、`{% get_language_info_list %}` は言語コードのリストをサポートしています。これをビューで実行すると:
```python
context = {"available_languages": ["en", "es", "fr"]}
return render(request, "mytemplate.html", context)
```
を使用すると、テンプレート内でそれらの言語のリストをイテレートできます:
```html+django
{% get_language_info_list for available_languages as langs %}
{% for lang in langs %} ... {% endfor %}
```
#### テンプレートフィルタ
いくつかの便利なフィルタが使えます:
- `{{ LANGUAGE_CODE|language_name }}` ("German")
- `{{ LANGUAGE_CODE|language_name_local }}` ("Deutsch")
- `{{ LANGUAGE_CODE|language_bidi }}` (False)
- `{{ LANGUAGE_CODE|language_name_translated }}` ("německy", when active language is Czech)
## 国際化: JavaScript コード内
JavaScript に対する翻訳には、いくつか問題があります:
- JavaScript コードは `gettext` 実行にアクセスできません。
- JavaScript コードは `.po` や `.mo` ファイルにアクセスできません; サーバーによって配布される必要があります。
- JavaScript 用の翻訳カタログはできる限り小さくなければなりません。
Django には、これらの問題に対する総合的な解決策が用意されています: 翻訳を JavaScript に渡し、`gettext` などを JavaScript 内から呼び出せるようにする方法です。
主な解決策は以下の `JavaScriptCatalog` ビューです。これは、`gettext` を擬似的に再現する関数と翻訳文字列の配列で JavaScript コードライブラリを生成します。
### `JavaScriptCatalog` ビュー
#### `class JavaScriptCatalog`
`gettext` インターフェイスを擬似的に再現する関数と翻訳文字列の配列で、JavaScriptのコードライブラリを生成するビューです。
**属性**
#### `domain`
ビューの出力に追加する文字列を含む翻訳ドメインです。デフォルトは `'djangojs'` です。
#### `packages`
インストールされたアプリケーション間の [`application names`](/ja/5.2/ref/applications/#django.apps.AppConfig.name) のリストです。これらのアプリケーションは `locale` ディレクトリを含んでいる必要があります。これらのカタログに加えて (常に含まれている) [`LOCALE_PATHS`](/ja/5.2/ref/settings/#std-setting-LOCALE_PATHS) 内で見つかった全てのカタログは、1 つのカタログに統合されます。デフォルトは `None` で、全ての [`INSTALLED_APPS`](/ja/5.2/ref/settings/#std-setting-INSTALLED_APPS) からの利用可能な翻訳は JavaScript の出力に渡されることを意味します。
**デフォルト値を使った例**:
```
from django.views.i18n import JavaScriptCatalog
urlpatterns = [
path("jsi18n/", JavaScriptCatalog.as_view(), name="javascript-catalog"),
]
```
**独自のパッケージを使った例**:
```
urlpatterns = [
path(
"jsi18n/myapp/",
JavaScriptCatalog.as_view(packages=["your.app.label"]),
name="javascript-catalog",
),
]
```
ルートの URLconf が [`i18n_patterns()`](#django.conf.urls.i18n.i18n_patterns)、`JavaScriptCatalog` を使っている場合、カタログが正しく生成されるように `i18n_patterns()` によるラップも必要となります。
`i18n_patterns()` **を使った例**:
```
from django.conf.urls.i18n import i18n_patterns
urlpatterns = i18n_patterns(
path("jsi18n/", JavaScriptCatalog.as_view(), name="javascript-catalog"),
)
```
翻訳の優先順位は、`packages` 引数で後に現れるパッケージの方が、最初に現れるものよりも高くなります。これは、同じリテラルに対する翻訳が衝突する場合に重要です。
サイト上で複数の `JavaScriptCatalog` ビューを使っていてそのうちのいくつかが同じ文字列を定義している場合、最後にロードされたカタログ内の文字列が優先されます。
### JavaScript 翻訳カタログを使う
カタログを使うには、以下のように動的に生成されたスクリプトを参照してください:
```html+django
```
これは、reverse URL を使用して、JavaScript カタログビューの URL をルックアップします。カタログがロードされると、JavaScript コードは以下のメソッドを使えるようになります:
- `gettext`
- `ngettext`
- `interpolate`
- `get_format`
- `gettext_noop`
- `pgettext`
- `npgettext`
- `pluralidx`
#### `gettext`
`gettext` 関数は、Python コード内の標準の `gettext` インターフェースと同じように動作します:
```
document.write(gettext("this is to be translated"))
```
#### `ngettext`
`ngettext` 関数は単語やフレーズを複数形にするインターフェースを提供します:
```javascript
const objectCount = 1 // or 0, or 2, or 3, ...
const string = ngettext(
'literal for the singular case',
'literal for the plural case',
objectCount
);
```
#### `interpolate`
`interpolate` 関数は表示形式の文字列の動的な記入をサポートします。補完の構文は Python を模しているので、`interpolate` 関数は位置および名前付きの補完の両方をサポートします。
- 位置による補完: `obj` は、表示されるのと同じ順番で要素の値が一致する `fmt` プレースホルダ内で連続的に補完される JavaScript Array オブジェクトを含んでいます。例えば:
```javascript
const formats = ngettext(
'There is %s object. Remaining: %s',
'There are %s objects. Remaining: %s',
11
);
const string = interpolate(formats, [11, 20]);
// string is 'There are 11 objects. Remaining: 20'
```
- 名前付きの補完: このモードは `named` パラメータを `true` として渡すことで選択されます。`obj` は JavaScript オブジェクトや結合配列を含みます。例えば:
```javascript
const data = {
count: 10,
total: 50
};
const formats = ngettext(
'Total: %(total)s, there is %(count)s object',
'there are %(count)s of a total of %(total)s objects',
data.count
);
const string = interpolate(formats, data, true);
```
ただし文字列補間は、やり過ぎるべきではありません。これはまだ JavaScript なので、コードは何度も正規表現による置換を行う必要があります。これは Python の文字列補間ほど速くはないので、本当に必要な場合（例えば、`ngettext` と組み合わせて適切な複数形を生成する場合など）に限定してください。
#### `get_format`
`get_format` 関数は設定済みの i18n 表示形式設定にアクセスでき、与えられた設定名に対して表示形式文字列を取り出します:
```javascript
document.write(get_format('DATE_FORMAT'));
// 'N j, Y'
```
以下の設定に対してアクセスします:
- [`DATE_FORMAT`](/ja/5.2/ref/settings/#std-setting-DATE_FORMAT)
- [`DATE_INPUT_FORMATS`](/ja/5.2/ref/settings/#std-setting-DATE_INPUT_FORMATS)
- [`DATETIME_FORMAT`](/ja/5.2/ref/settings/#std-setting-DATETIME_FORMAT)
- [`DATETIME_INPUT_FORMATS`](/ja/5.2/ref/settings/#std-setting-DATETIME_INPUT_FORMATS)
- [`DECIMAL_SEPARATOR`](/ja/5.2/ref/settings/#std-setting-DECIMAL_SEPARATOR)
- [`FIRST_DAY_OF_WEEK`](/ja/5.2/ref/settings/#std-setting-FIRST_DAY_OF_WEEK)
- [`MONTH_DAY_FORMAT`](/ja/5.2/ref/settings/#std-setting-MONTH_DAY_FORMAT)
- [`NUMBER_GROUPING`](/ja/5.2/ref/settings/#std-setting-NUMBER_GROUPING)
- [`SHORT_DATE_FORMAT`](/ja/5.2/ref/settings/#std-setting-SHORT_DATE_FORMAT)
- [`SHORT_DATETIME_FORMAT`](/ja/5.2/ref/settings/#std-setting-SHORT_DATETIME_FORMAT)
- [`THOUSAND_SEPARATOR`](/ja/5.2/ref/settings/#std-setting-THOUSAND_SEPARATOR)
- [`TIME_FORMAT`](/ja/5.2/ref/settings/#std-setting-TIME_FORMAT)
- [`TIME_INPUT_FORMATS`](/ja/5.2/ref/settings/#std-setting-TIME_INPUT_FORMATS)
- [`YEAR_MONTH_FORMAT`](/ja/5.2/ref/settings/#std-setting-YEAR_MONTH_FORMAT)
これは、Python によってレンダリングされる値と一貫性を持った表示形式を保守するために役立ちます。
#### `gettext_noop`
これは `gettext` 関数をエミュレートしますが、何もせず、渡されたものをそのまま返します:
```
document.write(gettext_noop("this will not be translated"))
```
これは、将来的に翻訳が必要なコードの部分をもみ消しておくのに役立ちます。
#### `pgettext`
`pgettext` 関数は Python の変数 ([`pgettext()`](/ja/5.2/ref/utils/#django.utils.translation.pgettext)) のように動作し、文脈的に翻訳される単語を提供します:
```
document.write(pgettext("month name", "May"))
```
#### `npgettext`
`npgettext` 関数も Python 変数 ([`npgettext()`](/ja/5.2/ref/utils/#django.utils.translation.npgettext)) のように動作し、**複数形の** 文脈的に翻訳される単語を提供します:
```javascript
document.write(npgettext('group', 'party', 1));
// party
document.write(npgettext('group', 'party', 2));
// parties
```
#### `pluralidx`
`pluralidx` 関数は [`pluralize`](/ja/5.2/ref/templates/builtins/#std-templatefilter-pluralize) テンプレートフィルタと同じように動作し、与えられた `count` が単語の複数形を使うべきかどうかを決めます:
```javascript
document.write(pluralidx(0));
// true
document.write(pluralidx(1));
// false
document.write(pluralidx(2));
// true
```
最も単純なケースでは、独自の複数形が必要ない場合、これは整数 `1` に対して `false` を返し、他の数に対して `true` を返します。
ただし、複数形は全ての言語でこのようにシンプルではありません。言語が複数形をサポートしていない場合、空の値が渡されます。
加えて、複数形に関して複雑なルールが存在する場合、カタログビューは条件付きの表現をレンダリングします。これは、値を `true` (複数形) と `false` (複数形 **ではない** ) のどちらにするかを評価します。
### `JSONCatalog` ビュー
#### `class JSONCatalog`
他のクライアントサイドのライブラリを使って翻訳を扱うためには、`JSONCatalog` を利用するのがいいでしょう。[`JavaScriptCatalog`](#django.views.i18n.JavaScriptCatalog) と似ていますが、JSON のレスポンスを返します。
使える値を知るには、[`JavaScriptCatalog`](#django.views.i18n.JavaScriptCatalog) を参照してください。また、`domain` と `packages` 属性を使用してください。
レスポンスの形式は以下の通りです:
```text
{
"catalog": {
# Translations catalog
},
"formats": {
# Language formats for date, time, etc.
},
"plural": "..." # Expression for plural forms, or null.
}
```
### 実行速度についての覚え書き
たくさんの JavaScript/JSON i18n ビューは全てのリクエストで `.mo` ファイルからカタログを生成します。出力は一定なので、少なくとも与えられたサイトのバージョンに対しては、キャッシュが有力な選択肢となります。
サーバーサイドのキャッシシュは CPU の負担を軽減します。 [`cache_page()`](/ja/5.2/topics/cache/#django.views.decorators.cache.cache_page) デコレータを使うと簡単に実装できます。翻訳を変更したときにキャッシュの無効部分をトリガーするには、以下の例にあるようにバージョンに依存したキープレフィックスを使ってください。もしくは、バージョンに依存した URL でビューをマッピングしてください:
```
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="jsi18n-%s" % get_version())(
JavaScriptCatalog.as_view()
),
name="javascript-catalog",
),
]
```
クライアントサイドのキャッシュは帯域を節約し、サイトの読み込みを速くします。ETags ([`ConditionalGetMiddleware`](/ja/5.2/ref/middleware/#django.middleware.http.ConditionalGetMiddleware)) を使っている場合、すでに適用済みです。それ以外の場合は、[条件付きデコレータ](/ja/5.2/topics/conditional-view-processing/#conditional-decorators) を参照してみてください。以下の例では、アプリケーションサーバを再起動するとキャッシュの効力がなくなります:
```
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",
),
]
```
デプロイ手順の一環として、JavaScript カタログを事前に生成し、静的ファイルとして提供することもできます。この革新的な手法は、[django-statici18n](https://pypi.org/project/django-statici18n/) によって実装されています。
## 国際化: URL パターン内
Django には、URL パターンを国際化するための 2 つの仕組みが用意されています:
- [`LocaleMiddleware`](/ja/5.2/ref/middleware/#django.middleware.locale.LocaleMiddleware) が、リクエストされた URL からアクティブにする言語を検出できるようにするため、URL パターンのルートに言語のプレフィックスを追加します。
- URL パターン自体を [`django.utils.translation.gettext_lazy()`](/ja/5.2/ref/utils/#django.utils.translation.gettext_lazy) 関数を通じて翻訳可能にする。
> **Warning**
>
> この 2 つのうちどちらを使う場合でも、各リクエストに対してアクティブな言語をセットすることが必要となります; 言い換えれば、[`MIDDLEWARE`](/ja/5.2/ref/settings/#std-setting-MIDDLEWARE) 設定内に [`django.middleware.locale.LocaleMiddleware`](/ja/5.2/ref/middleware/#django.middleware.locale.LocaleMiddleware) を記述しておく必要があります。
### URL パターンにおける言語プレフィックス
#### `i18n_patterns(*urls, prefix_default_language=True)`
この関数は、ルートの URLconf で使うことができ、Django は自動的に現在アクティブな言語のコードを [`i18n_patterns()`](#django.conf.urls.i18n.i18n_patterns) で定義された全ての URL パターンの先頭に追加します。
`prefix_default_language` を `False` にセットすると、デフォルト言語 ([`LANGUAGE_CODE`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_CODE)) からプレフィックスを除去します。これは、現在の URL を変更しないよう既存のサイトに翻訳を追加するとき、役に立ちます。
URL パターンの例:
```
from django.conf.urls.i18n import i18n_patterns
from django.urls import include, path
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//", news_views.category, name="category"),
path("/", news_views.details, name="detail"),
],
"news",
)
urlpatterns += i18n_patterns(
path("about/", about_views.main, name="about"),
path("news/", include(news_patterns, namespace="news")),
)
```
これらの URL パターンを定義すると、Django は自動的に `i18n_patterns` 関数で追加された URL パターンに言語プレフィックスを追加します。例:
```pycon
>>> 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/'
```
`prefix_default_language=False` と `LANGUAGE_CODE='en'` を使うと、URL は以下のようになります:
```pycon
>>> activate("en")
>>> reverse("news:index")
'/news/'
>>> activate("nl")
>>> reverse("news:index")
'/nl/news/'
```
> **Warning**
>
> [`i18n_patterns()`](#django.conf.urls.i18n.i18n_patterns) はルートの URLconf のみで使うことができます。インクルードされた URLconf で使うと [`ImproperlyConfigured`](/ja/5.2/ref/exceptions/#django.core.exceptions.ImproperlyConfigured) 例外を投げます。
> **Warning**
>
> 自動的に追加される言語プレフィックスと重複するようなプレフィックスを持った URL パターンにしないように注意してください。
### URL パターンを翻訳する
URL パターンは、[`gettext_lazy()`](/ja/5.2/ref/utils/#django.utils.translation.gettext_lazy) 関数を使って、翻訳可能にマークすることもできます。例えば:
```
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//"), news_views.category, name="category"),
path("/", news_views.details, name="detail"),
],
"news",
)
urlpatterns += i18n_patterns(
path(_("about/"), about_views.main, name="about"),
path(_("news/"), include(news_patterns, namespace="news")),
)
```
翻訳を作成した後に、[`reverse()`](/ja/5.2/ref/urlresolvers/#django.urls.reverse) 関数はアクティブな言語で URL を返します。例えば:
```pycon
>>> 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/'
```
> **Warning**
>
> ほとんどの場合、（ [`i18n_patterns()`](#django.conf.urls.i18n.i18n_patterns) を使用して）翻訳されたURLは、言語コードが接頭辞として付けられたパターンのブロック内でのみ使用することが最も良い選択です。不用意に翻訳された URL が翻訳されていない URL パターンと衝突するのを避けるためです。
### テンプレート内で逆引きする
ローカライズされた URL がテンプレート内でリバースされる場合、常に現在の言語が使用されます。他の言語の URL にリンクを貼るには、[`language`](#std-templatetag-language) テンプレートタグを使ってください。これは、テンプレートの囲まれた範囲内で、指定された言語を有効化します:
```html+django
{% load i18n %}
{% get_available_languages as languages %}
{% translate "View this category in:" %}
{% for lang_code, lang_name in languages %}
{% language lang_code %}
{{ lang_name }}
{% endlanguage %}
{% endfor %}
```
[`language`](#std-templatetag-language) タグは引数のみとして言語コードを予期します。
## ローカライズ: 言語ファイルを作成する方法
アプリケーションの文字列リテラルが後の翻訳にためにタグづけされ終わったら、翻訳自体を記述する (もしくは取得する) 必要があります。以下は、その方法です。
### メッセージファイル
最初のステップは、新しい言語に対する [message file](/ja/5.2/topics/i18n/#term-message-file) を作成することです。メッセージファイルはプレーンテキストファイルで、単一の言語を記述します。このファイルは、全ての翻訳可能な文字列とそれらがどのように与えられた言語で表示されるかを含みます。メッセージファイルは `.po` ファイル拡張子を持ちます。
Djangoには [`django-admin makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) というツールが用意してあり、これらのファイルの作成と保全を自動化します。
> **Gettext ユーティリティ**
>
> `makemessages` コマンド (と後述する `compilemessages`) は、GNU gettext ツールセットからのコマンドを使用します: `xgettext`、`msgfmt`、`msgmerge`、`msguniq` です。
>
> サポートされている `gettext` ユーティリティの最小バージョンは 0.19 です。
メッセージファイルを作成または更新するには、以下のコマンドを実行してください:
```shell
django-admin makemessages -l de
```
...ここでの `de` は作成したいメッセージファイルに対するロケール名 [locale name](/ja/5.2/topics/i18n/#term-locale-name) です。例えば、ブラジル系のポルトガル語に対する `pt_BR`、オーストリア系のドイツ語に対する `de_AT`、インドネシアに対する `id` などです。
スクリプトは、2 つの場所のうち 1 つから実行する必要があります:
- Django プロジェクトのルートディレクトリ (`manage.py` を含むところ)。
- Django アプリケーションのルートディレクトリ。
スクリプトは、プロジェクトのソースツリーもしくはアプリケーションのソースツリーを通じて実行され、翻訳用にマークされた全ての文字列 ([Djangoはどうやって翻訳を見つけるのか？](#how-django-discovers-translations) を参照して [`LOCALE_PATHS`](/ja/5.2/ref/settings/#std-setting-LOCALE_PATHS) を正しく設定してください) を抽出します。ディレクトリ `locale/LANG/LC_MESSAGES` にメッセージファイルを作成 (もしくは更新) します。`de` の例では、ファイルは `locale/de/LC_MESSAGES/django.po` となります。
プロジェクトのルートディレクトリから `makemessages` を実行したとき、抽出された文字列は自動的に適切なメッセージファイルへと分配されます。つまり、`locale` ディレクトリを含むアプリケーションのファイルから抽出された文字列は、そのディレクトリ下のメッセージファイルに格納されます。`locale` ディレクトリがないアプリケーションのファイルから抽出された文字列は、[`LOCALE_PATHS`](/ja/5.2/ref/settings/#std-setting-LOCALE_PATHS) 内に最初にリストアップされたディレクトリ下にあるメッセージファイルか、もしくは [`LOCALE_PATHS`](/ja/5.2/ref/settings/#std-setting-LOCALE_PATHS) が空の場合はエラーを生成します。
デフォルトでは [`django-admin makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) は `.html` 、 `.txt` または `py` のファイル拡張子を持つファイルを全て検査します。このデフォルトの動作をオーバーライドしたい場合は、 [`--extension`](/ja/5.2/ref/django-admin/#cmdoption-makemessages-extension) か `-e` オプションを使って検査するファイル拡張子を指定します:
```shell
django-admin makemessages -l de -e txt
```
複数の拡張子をカンマで区切るか、`-e` または `--extension` を複数回使用してください:
```shell
django-admin makemessages -l de -e html,txt -e xml
```
> **Warning**
>
> [JavaScript のソースコードからメッセージファイルを作成する](#creating-message-files-from-js-code) とき、 `-e js` **ではなく** 、特別な `djangojs` ドメインを使用する必要があります。
> **Jinja2 テンプレートを使う？**
>
> [`makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) はJinja2テンプレートの構文を理解しません。Jinja2テンプレートを含むプロジェクトから文字列を抽出するには、代わりに [Babel](https://babel.pocoo.org/en/latest/) の [Message Extracting](https://babel.pocoo.org/en/latest/messages.html#message-extraction) を使ってください。
>
> 以下は `babel.cfg` 設定ファイルの例です:
>
> ```ini
> # Extraction from Python source files
> [python: **.py]
>
> # Extraction from Jinja2 templates
> [jinja2: **.jinja]
> extensions = jinja2.ext.with_
> ```
>
> 使用しているすべての拡張機能をリストアップしてください！そうしないと、Babel はこれらの拡張機能によって定義されたタグを認識せず、それらを含む Jinja2 テンプレートを完全に無視します。
>
> Babel は [`makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) と似たような機能を提供し、一般的に置き換えることができ、 `gettext` に依存しません。より詳しい情報は [メッセージカタログの操作](https://babel.pocoo.org/en/latest/messages.html) に関するドキュメントを参照してください。
> **gettext がない？**
>
> `gettext` ユーティリティがインストールされていない場合、 [`makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) は空のファイルを作成します。そのような場合は、 `gettext` ユーティリティをインストールするか、英語のメッセージファイル (`locale/ja/LC_MESSAGES/django.po`) があれば、それをコピーして、空の翻訳ファイルから始めてください。
> **Windows で動作する？**
>
> あなたが Windows を使っていて、[`makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) が動作するように GNU gettext ユーティリティをインストールする必要がある場合は、[Windows での gettext](#gettext-on-windows) で詳しい情報を参照してください。
各 `.po` ファイルは、翻訳保守者の連絡先情報などのわずかなメタデータを含みますが、大部分は **メッセージ** のリストです。これは、特定の言語に対する、翻訳文字列と実際の翻訳済みテキストのマッピングです。
例えば以下のように、Django アプリケーションが `"Welcome to my site."` に対する翻訳文字列を含んでいる場合、:
```
_("Welcome to my site.")
```
...それから [`django-admin makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) は `.po` ファイルを生成し、そのファイルは以下のようなスニペットを含みます -- メッセージ:
```po
#: path/to/python/module.py:23
msgid "Welcome to my site."
msgstr ""
```
簡単に説明すると:
- `msgid` は翻訳文字列で、ソース内に存在します。変更しないでください。
- `msgstr` はあなたが言語に対応する翻訳を記述する場所です。これは空の状態から始まるので、変更するのはあなたの役割です。翻訳をクオートで囲むようにしてください。
- 利便性のため、各メッセージは、`#` でプレフィックスされ `msgid` 行の直前に位置するコメント行の形式の中に、翻訳文字列がどこから拾い集められたかを示すファイル名と行数を含みます。
長いメッセージは特殊なケースです。そこでは、`msgstr` (もしくは `msgid`) 直後の最初の文字列は空の文字列です。それからコンテンツ自身が行ごとに 1 つの文字列として次の数行にわたって記述されます。これらの文字列は直接連結されます。文字列内で最後のスペースを忘れないでください; さもなくば、空白スペースなしで接合されることになります！
> **文字コードを気にしてください**
>
> `gettext` ツールが内部的に動作する方法および非 ASCII ソースの文字列を Django のコアとあなたのアプリケーション内で許容するために、 `.po` ファイルに対するエンコーディングとして UTF-8 ( `.po` ファイルが生成される際のデフォルトです) を **使わなければなりません**。これは、全員が同じエンコーディングを使用することを意味し、Django が `.po` ファイルを処理する際に重要となります。
> **Fuzzy（あいまいな）エントリー**
>
> [`makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) は翻訳が以前に翻訳された文字列から推測される場合などに、あいまい (fuzzy) としてマークされた翻訳エントリーを生成することがあります。デフォルトでは、あいまいなエントリは [`compilemessages`](/ja/5.2/ref/django-admin/#django-admin-compilemessages) によって処理されません。
新しい翻訳文字列に対して全てのコードとテンプレートを再検査して **全ての** 言語に対する全てのメッセージファイルを更新するには、以下を実行してください:
```shell
django-admin makemessages -a
```
### メッセージファイルをコンパイルする
メッセージファイルを作成した後 -- そして変更を加えたときそれぞれで -- `gettext` による使用のために、より効率的な形式にコンパイルする必要があります。[`django-admin compilemessages`](/ja/5.2/ref/django-admin/#django-admin-compilemessages) ユーティリティを利用してください。
このツールは、全ての有効な `.po` ファイルを通じて動作し、`.mo` ファイルを生成します。これは `gettext` による使用のために最適化されたバイナリファイルです。[`django-admin makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) を実行した同じディレクトリで、以下のように [`django-admin compilemessages`](/ja/5.2/ref/django-admin/#django-admin-compilemessages) を実行してください:
```shell
django-admin compilemessages
```
これで終わりです。翻訳は使う準備ができました。
> **Windows で動作する？**
>
> あなたが Windows を使っていて、[`django-admin compilemessages`](/ja/5.2/ref/django-admin/#django-admin-compilemessages) が動作するように GNU gettext ユーティリティをインストールする必要がある場合は、[Windows での gettext](#gettext-on-windows) で詳しい情報を参照してください。
> **.po ファイル: エンコーディングと BOM の使用**
>
> Django は、UTF-8 でエンコードされ BOM (Byte Order Mark) を持たない `.po` ファイルのみをサポートします。そのため、テキストエディタがデフォルトでこれらのマークをファイルの最初に追加した場合、再構成する必要があります。
### トラブルシューティング: `gettext()` がパーセント文字を伴う文字列内で `python-format` を誤って見つけてしまう
例えば、パーセント記号に続いて空白と [文字列変換タイプ](https://docs.python.org/3/library/stdtypes.html#old-string-formatting) がある文字列（例: `_("10% interest")`）などに、[`gettext()`](/ja/5.2/ref/utils/#django.utils.translation.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 つ重ねてエスケープします:
```
from django.utils.translation import gettext as _
output = _("10%% interest")
```
もしくは `no-python-format` を使ってパーセント文字がリテラルとして扱われるようにします:
```
# xgettext:no-python-format
output = _("10% interest")
```
### JavaScript ソースコードからメッセージファイルを作成する
他の Django メッセージファイルと同じ方法で ([`django-admin makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) ツールを使って) 作成や更新を行います。唯一の違いは、`-d djangojs` パラメータを提供することによって、gettext 用語がドメインであること (このケースでは `djangojs` ドメイン) を、以下のように明示的に指定する必要があることです:
```shell
django-admin makemessages -d djangojs -l de
```
これは、ドイツ語に対して JavaScript 用のメッセージファイルを作成または更新します。メッセージファイルの更新後、通常の Django ファイルと同様の方法で [`django-admin compilemessages`](/ja/5.2/ref/django-admin/#django-admin-compilemessages) を実行してください。
### Windows での `gettext`
これはメッセージ ID を抽出したり、メッセージファイル(`.po`)をコンパイルしたい人だけが必要です。翻訳作業そのものは既存のこの種類のファイルを編集することになりますが、独自のメッセージファイルを作成したい場合や、変更したメッセージファイルをテストしたりコンパイルしたりしたい場合は、 [コンパイル済みのバイナリインストーラ](https://mlocati.github.io/articles/gettext-iconv-windows.html) をダウンロードしてください。
`xgettext --version` コマンドが正しく動作する限り、他の場所で入手した `gettext` バイナリを使うこともできます。Windows のコマンドプロンプトでコマンド `xgettext --version` を入力すると、ポップアップウィンドウに "`xgettext.exe` has generated errors and will be closed by Windows" と表示される場合は、 `gettext` パッケージを使って Django の翻訳ユーティリティを使おうとしないでください。
### `makemessages` コマンドをカスタマイズする
`xgettext` に追加のパラメータを渡したい場合、独自の [`makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) コマンドを作成して、その `xgettext_options` 属性をオーバーライドする必要があります:
```
from django.core.management.commands import makemessages
class Command(makemessages.Command):
xgettext_options = makemessages.Command.xgettext_options + ["--keyword=mytrans"]
```
もっと柔軟に使う必要があるとき場合には、[`makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) コマンドに新しい引数を追加することもできます:
```
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)
```
## その他
### `set_language` リダイレクトビュー
#### `set_language(request)`
利便性のために、 Django にはビュー [`django.views.i18n.set_language()`](#django.views.i18n.set_language) が付属しており、 ユーザの言語設定を行い、指定された URL にリダイレクトします。デフォルトでは前のページに戻ります。
URLconfに以下の行を追加して、このビューを有効にします:
```
path("i18n/", include("django.conf.urls.i18n")),
```
(この例では `/i18n/setlang/` でビューを利用できるようにしていることに注意してください)。
> **Warning**
>
> 上記の URL を [`i18n_patterns()`](#django.conf.urls.i18n.i18n_patterns) 内に含めないようにしてください。正しく動作するためには、それ自身が言語に依存せず独立している必要があります。
このビューは `POST` メソッド経由で呼び出され、 `language` パラメータがリクエスト内に設定されることを想定しています。ビューはデフォルトでは `django_language` という名前のクッキーに言語選択を保存します。（クッキー名は [`LANGUAGE_COOKIE_NAME`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_COOKIE_NAME) 設定によって変更できます。）
言語選択を設定した後、Django は `POST` または `GET` データの `next` パラメータを探します。もしそれが見つかり、 Django が安全な URL (つまり、別のホストを指しておらず、安全なスキームを使っている) と判断した場合、その URL へのリダイレクトが実行されます。そうでない場合、 Django はリクエストの性質に応じて、 `Referer` ヘッダの URL にリダイレクトしたり、ヘッダが設定されていない場合は `/` にリダイレクトしたりします:
- リクエストが(`Accept` HTTPヘッダに基づいて)HTMLコンテンツを受け入れる場合、フォールバックは常に実行されます。
- リクエストがHTMLを受け付けない場合、 `next` パラメータが指定されている場合のみフォールバックが実行されます。そうでない場合はステータスコード 204 (No Content) が返されます。
以下はHTMLテンプレートコードの例です:
```html+django
{% load i18n %}
```
この例では、 Django は `redirect_to` コンテキスト変数で、ユーザがリダイレクトされるページの URL を調べます。
### 明示的にアクティブな言語をセットする
明示的に、現在のセッションに対して、アクティブな言語をセットしたくなるかもしれません。例えば、他のシステムを活用すれば、ユーザの言語設定を取得できます。[`django.utils.translation.activate()`](/ja/5.2/ref/utils/#django.utils.translation.activate) はすでに紹介済みですね。これは現在のスレッドに対してのみ適用されます。セッション全体の言語をクッキーに恒久的に保持するには、レスポンスに [`LANGUAGE_COOKIE_NAME`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_COOKIE_NAME) クッキーを設定します。
```
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)
```
通常、両方を使う必要があるでしょう: [`django.utils.translation.activate()`](/ja/5.2/ref/utils/#django.utils.translation.activate) はこのスレッドに対して言語を変更します。そして、クッキーをセットするとこの設定が将来のリクエストに恒久的に反映されます。
### ビューやテンプレートの外で翻訳を使う
Django はビューやテンプレートで使うための豊富な国際化ツールセットを提供していますが、Django 固有のコードに使い方を限定しているわけではありません。Django の翻訳システムを使えば、任意のテキストを Django がサポートしている任意の言語に翻訳できます (もちろん、適切な翻訳カタログが存在する場合に限ります)。翻訳カタログを読み込んで有効にし、テキストを好きな言語に翻訳することも可能ですが、元の言語に戻すことを忘れないでください。翻訳カタログの有効化はスレッド単位で行われ、そのような変更は同じスレッドで実行されているコードに影響するからです。
例:
```
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
```
この関数を `'de'` という値で呼び出すと、 [`LANGUAGE_CODE`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_CODE) やミドルウェアで設定されている言語に関係なく、 `"Willkommen"` が返されます。
特に注目すべき関数は、現在のスレッドで使われている言語を返す [`django.utils.translation.get_language()`](/ja/5.2/ref/utils/#django.utils.translation.get_language) 、現在のスレッドの翻訳カタログを有効にする [`django.utils.translation.activate()`](/ja/5.2/ref/utils/#django.utils.translation.activate) 、与えられた言語が Django でサポートされているかどうかをチェックする [`django.utils.translation.check_for_language()`](/ja/5.2/ref/utils/#django.utils.translation.check_for_language) です。
より簡潔なコードを書くために、コンテキストマネージャ [`django.utils.translation.override()`](/ja/5.2/ref/utils/#django.utils.translation.override) も用意されています、これは実行時に現在の言語を保存し、終了時にそれを復元します。これを使うと、上の例は次のようになります:
```
from django.utils import translation
def welcome_translated(language):
with translation.override(language):
return translation.gettext("welcome")
```
### 言語クッキー
言語クッキーのオプションを調整するには、多くの設定が使用できます:
- [`LANGUAGE_COOKIE_NAME`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_COOKIE_NAME)
- [`LANGUAGE_COOKIE_AGE`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_COOKIE_AGE)
- [`LANGUAGE_COOKIE_DOMAIN`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_COOKIE_DOMAIN)
- [`LANGUAGE_COOKIE_HTTPONLY`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_COOKIE_HTTPONLY)
- [`LANGUAGE_COOKIE_PATH`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_COOKIE_PATH)
- [`LANGUAGE_COOKIE_SAMESITE`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_COOKIE_SAMESITE)
- [`LANGUAGE_COOKIE_SECURE`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_COOKIE_SECURE)
## 実装時のためのノート
### Djangoの翻訳の特徴
Django の翻訳システムは Python に付属している標準の `gettext` モジュールを使います。 `gettext` を知っていれば、Django が翻訳を行う方法について、以下のような特徴があることに気づくかもしれません:
- 文字列ドメインは `django` または `djangojs` です。この文字列ドメインは、共通のメッセージファイルライブラリ (通常は `/usr/share/locale/`) にデータを保存する異なるプログラムを区別するために使用されます。 `django` ドメインは Python とテンプレートの翻訳文字列に使われ、グローバル翻訳カタログに読み込まれます。 `djangojs` ドメインはできるだけ小さくなるように、 JavaScript の翻訳カタログにだけ使われます。
- Django は `xgettext` だけを使っているわけではありません。これは `xgettext` と `msgfmt` を Python でラップしたものです。これは主に利便性のためです。
### Django はどうやって言語の優先順位を検出するのか？
翻訳を準備したら、あるいは Django に付属している翻訳を使いたい場合は、アプリの設定で翻訳を有効にする必要があります。
Djangoは、インストール全体、特定のユーザー、またはその両方に対して、使用する言語を決定する非常に柔軟なモデルを持っています。
インストール全体の優先言語を設定するには、 [`LANGUAGE_CODE`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_CODE) を設定してください。Django はこの言語をデフォルトの翻訳として使います。ロケールミドルウェアが採用するメソッド (下記参照) を使って、より適切な翻訳が見つからなかった場合の最終的な翻訳です。
Django を母国語で動かしたいだけなら、 [`LANGUAGE_CODE`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_CODE) を設定し、対応する [メッセージファイル](/ja/5.2/topics/i18n/#term-message-file) とそのコンパイルバージョン (`.mo`) が存在することを確認するだけです。
各ユーザに好きな言語を指定させたい場合は、 `LocaleMiddleware` を使用する必要があります。ロケール ミドルウェア `LocaleMiddleware` はリクエストのデータに基づいて言語を選択できるようにします。これは各ユーザのためにコンテンツをカスタマイズします。
`LocaleMiddleware` を使うには、`django.middleware.locale.LocaleMiddleware'` を [`MIDDLEWARE`](/ja/5.2/ref/settings/#std-setting-MIDDLEWARE) 設定に追加します。ミドルウェアの順番は重要なので、以下のガイドラインに従ってください:
- 最初にインストールされるミドルウェアの1つであることを確認してください。
- なぜなら `LocaleMiddleware` はセッションデータを利用するからです。また、 `CommonMiddleware` はリクエストされたURLを解決するために有効な言語を必要とするので、 `CommonMiddleware` の前に来る必要があります。
- `CacheMiddleware` を使用する場合は、その後ろに `LocaleMiddleware` を記述してください。
たとえば、[`MIDDLEWARE`](/ja/5.2/ref/settings/#std-setting-MIDDLEWARE) は次のようになります:
```
MIDDLEWARE = [
"django.contrib.sessions.middleware.SessionMiddleware",
"django.middleware.locale.LocaleMiddleware",
"django.middleware.common.CommonMiddleware",
]
```
(ミドルウェアについては [ミドルウェアのドキュメント](/ja/5.2/topics/http/middleware/) を参照してください)。
`LocaleMiddleware` は以下のアルゴリズムに従ってユーザーの言語設定を決定しようとします:
- 最初に、リクエストされたURLの言語プレフィックスを探します。 これはルートの URLconf で `i18n_patterns` 関数を使用している場合にだけ実行されます。言語プレフィックスとURLパターンの国際化方法についての詳細は [国際化: URL パターン内](#url-internationalization) を参照してください。
- それに失敗すれば、クッキーを探します。
使用されるクッキーの名前は [`LANGUAGE_COOKIE_NAME`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_COOKIE_NAME) 設定によって設定されます。(デフォルトの名前は `django_language` です)。
- それに失敗した場合は `Accept-Language` HTTPヘッダを調べます。このヘッダはブラウザから送られ、サーバにどの言語を優先するのかを伝えます。Django は、翻訳可能な言語が見つかるまで、ヘッダの各言語を試します。
- それに失敗すると、グローバルな [`LANGUAGE_CODE`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_CODE) 設定を使用します。
メモ:
- これらの場所では、言語設定は標準の [言語コード](/ja/5.2/topics/i18n/#term-language-code) 文字列で指定します。たとえば、ブラジルポルトガル語は `pt-br` です。
- ベース言語が利用可能で、指定されたサブ言語が利用できない場合、 Django はベース言語を使います。たとえば、ユーザが `de-at` (オーストリアのドイツ語) を指定したが、 Django には `de` しかない場合、 Django は `de` を使います。
- 選択できるのは [`LANGUAGES`](/ja/5.2/ref/settings/#std-setting-LANGUAGES) 設定にリストされている言語だけです。言語選択を提供されている言語のサブセットに制限したい場合(アプリケーションがすべての言語を提供していないため)、 [`LANGUAGES`](/ja/5.2/ref/settings/#std-setting-LANGUAGES) に言語のリストを設定します。たとえば、次のようにします：
```
LANGUAGES = [
("de", _("German")),
("en", _("English")),
]
```
この例では、自動選択できる言語をドイツ語と英語（および `de-ch` や `en-us` のようなサブ言語）に制限しています。
- 前の箇所で説明したように、カスタムの [`LANGUAGES`](/ja/5.2/ref/settings/#std-setting-LANGUAGES) 設定を定義すれば、言語名を翻訳文字列としてマークできます。ただし、循環インポートを避けるために、 [`gettext()`](/ja/5.2/ref/utils/#django.utils.translation.gettext) の代わりに [`gettext_lazy()`](/ja/5.2/ref/utils/#django.utils.translation.gettext_lazy) を使ってください。
以下はサンプルの設定ファイルです:
```
from django.utils.translation import gettext_lazy as _
LANGUAGES = [
("de", _("German")),
("en", _("English")),
]
```
`LocaleMiddleware` がユーザの設定を決定すると、その設定を [`HttpRequest`](/ja/5.2/ref/request-response/#django.http.HttpRequest) の `request.LANGUAGE_CODE` として利用できるようにします。この値はビューのコードで自由に読み込むことができます。以下に例を示します:
```
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.")
```
静的な(ミドルウェアを使わない)翻訳では、言語は `settings.LANGUAGE_CODE` にあり、動的な(ミドルウェアを使った)翻訳では `request.LANGUAGE_CODE` にあることに注意してください。
### Djangoはどうやって翻訳を見つけるのか？
実行時に、 Django はリテラルと翻訳の統合カタログをメモリ内に構築します。これを実現するために、コンパイルされた [メッセージファイル](/ja/5.2/topics/i18n/#term-message-file) (`.mo`) を読み込むために異なるファイルパスを調べる順序と、同じリテラルに対して複数の翻訳がある場合の優先順位について、以下のアルゴリズムに従って翻訳を探します:
1. [`LOCALE_PATHS`](/ja/5.2/ref/settings/#std-setting-LOCALE_PATHS) に列挙されているディレクトリが最も優先され、最初に記述されているものが後に記述されているものよりも優先されます。
2. 次に、 [`INSTALLED_APPS`](/ja/5.2/ref/settings/#std-setting-INSTALLED_APPS) に列挙されている各インストール済みアプリの `locale` ディレクトリを探し、存在すればそれを使用します。 このとき、最初に指定されたものが後に指定されたものよりも優先されます。
3. 最後に、 [django/conf/locale](https://github.com/django/django/blob/stable/5.2.x/django/conf/locale) にある Django が提供する基本翻訳がフォールバックとして使われます。
> **See also**
>
> JavaScriptアセットに含まれるリテラルの翻訳は同じようなアルゴリズムで検索されますが、同じではありません。詳細は [`JavaScriptCatalog`](#django.views.i18n.JavaScriptCatalog) を参照してください。
>
> また、 [`FORMAT_MODULE_PATH`](/ja/5.2/ref/settings/#std-setting-FORMAT_MODULE_PATH) を設定すれば、 [カスタムフォーマットファイル](/ja/5.2/topics/i18n/formatting/#custom-format-files) を [`LOCALE_PATHS`](/ja/5.2/ref/settings/#std-setting-LOCALE_PATHS) ディレクトリに置くこともできます。
すべての場合において、翻訳を含むディレクトリの名前は [locale name](/ja/5.2/topics/i18n/#term-locale-name) 表記で指定します。例えば `de`、`pt_BR`、`es_AR` などです。地域言語バリアントの未翻訳の文字列は一般言語の翻訳を使用します。たとえば、未翻訳の `pt_BR` 文字列は `pt` の翻訳を使用します。
こうすることで、独自の翻訳を含むアプリケーションを書くことができ、プロジェクトでベースとなる翻訳を上書きできます。あるいは、いくつかのアプリから大きなプロジェクトを作り、すべての翻訳を、作成中のプロジェクトに特化した1つの大きな共通メッセージファイルにまとめることもできます。選択肢はあなたの自由です。
メッセージ・ファイルのリポジトリはすべて同じ構造になっています。それらは下記のようなものです:
- 設定ファイルの [`LOCALE_PATHS`](/ja/5.2/ref/settings/#std-setting-LOCALE_PATHS) にリストされているすべてのパスは、`/LC_MESSAGES/django.(po|mo)` で検索されます。
- `$APPPATH/locale//LC_MESSAGES/django.(po|mo)`
- `$PYTHONPATH/django/conf/locale//LC_MESSAGES/django.(po|mo)`
メッセージファイルを作成するには [`django-admin makemessages`](/ja/5.2/ref/django-admin/#django-admin-makemessages) ツールを使用します。また、 [`django-admin compilemessages`](/ja/5.2/ref/django-admin/#django-admin-compilemessages) を使って、 `gettext` が使用するバイナリファイル `.mo` を作成します。
また、 [`django-admin compilemessages --settings=path.to.settings`](/ja/5.2/ref/django-admin/#django-admin-compilemessages) を実行すると、コンパイラが [`LOCALE_PATHS`](/ja/5.2/ref/settings/#std-setting-LOCALE_PATHS) 設定にあるすべてのディレクトリを処理するようになります。
### 英語以外の言語をベース言語として使う
Django は、翻訳可能なプロジェクト内の元の文字列は英語で書かれているという一般的な前提に立っています。他の言語を選ぶこともできますが、ある制限に注意する必要があります:
- `gettext` はオリジナルのメッセージに対して2つの複数形しか提供しないので、もしベース言語の複数形のルールが英語と異なる場合は、すべての複数形を含むようにベース言語の翻訳も提供する必要があります。
- 英語のバージョンが有効になっていて、英語の文字列がない場合、フォールバック言語はプロジェクトの [`LANGUAGE_CODE`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_CODE) ではなく、オリジナルの文字列になります。たとえば、[`LANGUAGE_CODE`](/ja/5.2/ref/settings/#std-setting-LANGUAGE_CODE) がスペイン語に設定されていて、元の文字列がロシア語で書かれているサイトを訪れた英語のユーザは、スペイン語ではなくロシア語のテキストを見ることになります。