概要¶

国際化のゴールは、一つの Web アプリケーションが複数の言語でコンテンツや機能 を提供できるようにすることにあります。

Django 開発者は、最小限のフックを Python コードとテンプレートに埋め込むこと で国際化というゴールにたどり着けます。これらのフックは 翻訳文字列 (translation string) と呼ばれています。翻訳文字列は Django に「このテキストについてエンドユーザの言語に合ったテキストがあるなら、テキ ストを翻訳して出力せよ」と指示します。

Django はこれらのフックに注意して、ユーザの言語設定に合わせて Web アプリケー ションをオンザフライで翻訳します。

Django が行っているのは、本質的には以下の二つの作業です:

• 開発者やテンプレートの作者に、アプリケーションのどの部分を翻訳できるか 指定させます。
• 指定したフックを使って、特定のユーザの言語設定に従って Web アプリケー ションを翻訳します。

国際化が必要ない場合¶

Django の国際化フックはデフォルトで有効になっているので、フレームワークの一 部で i18n がらみのわずかなオーバヘッドが生じています。国際化の機能を使いた くなければ、設定ファイルで USE_I18N = False を設定し てください。 USE_I18N を False に設定すると、 Django は国際 化機構をロードしないよう最適化を行います。

この場合、 TEMPLATE_CONTEXT_PROCESSORS からも 'django.core.context_processors.i18n' を外すことになるでしょう。

国際化が必要な場合: 3 つのステップ¶

1. 翻訳対象文字列を Python コードやテンプレートに埋め込みます。
2. サポートしたい言語について、翻訳対象文字列に対応する翻訳を行います。
3. Django の設定でロケールミドルウェアを有効化します。

1. 翻訳文字列の指定方法¶

翻訳文字列 (translation string) は、「このテキストを翻訳対象にする」という 指定を行います。翻訳文字列は Python コードにもテンプレートにも現れます。翻 訳可能な文字列をマークしておくのは作者の役割であり、翻訳システムはマークさ れた文字列しか翻訳対象にしません。

from django.utils.translation import ugettext as _

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

from django.utils.translation import ugettext
def my_view(request):
    output = ugettext("Welcome to my site.")
    return HttpResponse(output)

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)

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

from django.utils.translation import ugettext_lazy

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

from django.utils.translation import ugettext_lazy as _

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

from django.utils.translation import ugettext_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 = _('mythings')

from django.utils.translation import ungettext
def hello_world(request, count):
    page = ungettext('there is %(count)d object', 'there are %(count)d objects', count) % {
        'count': count,
    }
    return HttpResponse(page)

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

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

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

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

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

{% get_current_language as LANGUAGE_CODE %}
{% get_available_languages as LANGUAGES %}
{% get_current_language_bidi as LANGUAGE_BIDI %}

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

from django.utils.translation import string_concat
...
name = ugettext_lazy(u'John Lennon')
instrument = ugettext_lazy(u'guitar')
result = string_concat([name, ': ', instrument])

from django.utils.functional import allow_lazy

def fancy_utility_function(s, ...):
    # Do some conversion on string 's'
    ...
fancy_utility_function = allow_lazy(fancy_utility_function, unicode)

2. 言語ファイルの作成¶

文字列に翻訳用のタグをつけたら、今度は翻訳文自体を書く (または手に入れる) 必要があります。ここでは翻訳文を書く方法について示します。

django-admin.py makemessages -l de

django-admin.py makemessages -l de -e txt

django-admin.py makemessages -l=de -e=html,txt -e xml

_("Welcome to my site.")

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

django-admin.py makemessages -a

django-admin.py compilemessages

3. 言語設定の検出メカニズム¶

翻訳の準備を完了した、あるいは Django 付属の翻訳を使いたいだけなら、あとは アプリケーションで翻訳を有効にするだけです。

背後では、 Django はユーザの使用言語を決めるモデルを備えています。このモデ ルは柔軟で、インストール全体、あるいは特定のユーザ、またはその両方に対して 使用言語を決定できます。

インストール全体での使用言語を設定するには、 LANGUAGE_CODE を設 定します。 Django この設定をデフォルトの翻訳言語、すなわち他の適切な翻訳が ない場合に試みる言語に設定します。

Django をネイティブの言語で動かしたいだけで、かつ自分の言語に対する言語ファ イルをすでに準備しているのなら、 LANGUAGE_CODE を設定するだけで済みます。

個々のユーザが自分の使いたい言語を選択できるようにするには LocaleMiddleware を使ってください。 LocaleMiddleware は、リクエスト に埋め込まれたデータに基づいた言語の選択を可能にし、ユーザごとにコンテンツ をカスタマイズします。

LocaleMiddleware を使うには、 MIDDLEWARE_CLASSES 設定に 'django.middleware.locale.LocaleMiddleware' を追加します。ミドルウェア の順番は重要で、以下のガイドラインに従って下さい:

• まず、インストール済みのミドルウェアの先頭にくるようにしてください。
• LocaleMiddleware はセッションを使うので、 SessionMiddleware の後ろに配置してください。
• CacheMiddleware を使っているなら、その後ろに LocaleMiddleware を配置してください。

例えば、 MIDDLEWARE_CLASSES は以下のようになります:

MIDDLEWARE_CLASSES = (
   'django.contrib.sessions.middleware.SessionMiddleware',
   'django.middleware.locale.LocaleMiddleware',
   'django.middleware.common.CommonMiddleware',
)

(ミドルウェアの詳細は ミドルウェアのドキュメント を参照してください。)

LocaleMiddleware はユーザの言語設定を以下のようなアルゴリズムで決定しよ うと試みます:

• まず、現在のユーザのセッションに django_language キーがないか探し ます。

• なければ、クッキーを探します。

  Django 1.0 で変更されました.

  バージョン 0.96 以前の Djangoでは、クッキーの名前は django_language にハードコードされていました。 1.0 では、クッキー の名前を LANGUAGE_COOKIE で設定します。(クッキーのデフォル ト名は django_language です。)

• なければ、 Accept-Language HTTP ヘッダを探します。このヘッダはブ ラウザから送信され、サーバに対して順位つきで言語設定を知らせてきます。 Djang はこの設定を順に調べ、利用可能な翻訳のある言語を探します。

• なければ、グローバルに設定された LANGUAGE_CODE の設定を使います。

注意:

• 上記のどのステップでも、言語設定は標準の言語名表記法に従った文字列で 書かれているものと想定しています。例えば、ブラジル系ポルトガル語は pt-br です。

• 基本言語 (base language) が指定されていて、副言語 (sublanguage) が指 定されていない場合、 Django は基本言語の設定を優先します。例えば、ユー ザが de-at (オーストリアドイツ語) を指定しているのに対して、 Django 側には de のしかない場合、 Django は de を使います。

• LANGUAGES 設定にリストアップした言語しか選択できません。 (全ての言語に対する翻訳を提供できないなどの理由で) 言語選択を指定の言 語のサブセットに制限したい場合には、 LANGUAGES を設定します。例え ば:

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

  この例では、自動生成されるメニューで利用可能な言語をドイツ語:de と 英語:en (および de-ch や en-us のような副言語) に制限しています。

• 上の項で説明したように、カスタムの LANGUAGES 設定を行った場合、そ の言語を翻訳対象文字列に含めても構いません。ただし、 django.utils.translation の ugettext() ではなく、「ダミーの」 ugettext() でマークしてください。循環 import を防ぐため、 決して 設定ファイル中で django.utils.translation を import しないでくだ さい。

  カスタム LANGUAGES のマークアップは「ダミーの」 ugettext() 関 数で解決します。以下に設定ファイルでの記述例を示します:

  ugettext = lambda s: s
  
  LANGUAGES = (
      ('de', ugettext('German')),
      ('en', ugettext('English')),
  )
  

  このように設定しておいても、 django-admin.py makemessages は翻訳 文字列を検出して翻訳対象としてマークします。ただし、実行時の翻訳はお こなわれません。したがって、実行時には LANGUAGES を使うコードを 本当の ugettext() でラップしておかねばなりません。

• LocaleMiddleware で選択できるのは、 Django が基本的な部分の翻訳を 提供している言語だけです。 Django のソースツリーの翻訳セットに入って いない言語の翻訳を提供したければ、まずその言語むけの基本部分の翻訳を 提供する必要があります。例えば、Django はテクニカルメッセージ ID (technical message ID) を使って日付や時刻のフォーマットを解釈するので、 システムを正しく動作させるには少なくともこうした部分の翻訳が必要にな ります。

  作業を始めるには、まず英語用の .po ファイルをコピーするとよいでしょ う。少なくともテクニカルメッセージだけは翻訳します。バリデーション時 のメッセージもやっておくとよいでしょう。

  テクニカルメッセージ ID は簡単に区別できます。メッセージ ID は全て大 文字でできているからです。このメッセージ ID は他のメッセージと同じよ うに翻訳してよいものではなく、ローカルの正しい形式を指定せねばなりま せん。例えば、 DATETIME_FORMAT (あるいは DATE_FORMAT や TIME_FORMAT) の場合、自分の言語における正しいフォーマット文字列を 指定せねばなりません。フォーマットは now テンプレートタグで使われ ているフォーマット文字列と同じ文法に従います。

LocaleMiddleware がユーザ設定を検出すると、その設定に HttpRequest の request.LANGUAGE_CODE でアクセスで きます。この値はビューコードで自由に読みだしてかまいません。以下に一例を挙 げます:

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 は以下のアルゴリズムに従って翻訳を探します:

• まず、現在呼び出されているビューの入っているアプリケーションディレク トリ下に locale ディレクトリを探します。現在選択されている言語に 対応する翻訳があれば、その翻訳をインストールします。
• 次に、プロジェクトディレクトリ下に locale ディレクトリを探します。 翻訳があれば、その翻訳をインストールします。
• 最後に、 django/conf/locale にある Django 付属の翻訳をチェックし ます。

こうすることで、独自の翻訳の入ったアプリケーションを書いたり、基本の翻訳の 内容をプロジェクトパスに置いた翻訳でオーバライドしたりできます。また、複数 の小さなアプリケーションで大きめのプロジェクトを構築するときに、全ての翻訳 を一つのプロジェクト単位のメッセージファイルにまとめておけます。どういう方 法をとるかはユーザ次第です。

メッセージファイルリポジトリも同じような構成になっています:

• $APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)
• $PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)
• 設定ファイルの LOCALE_PATHS に指定されている全てのパスを指定順に 検索して <language>/LC_MESSAGES/django.(po|mo) を探します。
• $PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)

メッセージファイルの作成には、 Django メッセージファイルと同じ django-admin.py makemessages ツールを使って下さい。ツールの実行は正しい 場所、すなわち conf/locale (ソースツリーの場合) か、あるいは locale (アプリケーションメッセージやプロジェクトメッセージの場合) ディレクトリのあ るディレクトリで行わねばなりません。また、 gettext の使うバイナリ形式の django.mo ファイルを生成するには django-admin.py compilemessages を 使います。

django-admin.py compilemessages --settings=path.to.settings を実行すれ ば、コンパイラに LOCALE_PATHS に設定された全てのディレクトリを処理させ られます。

アプリケーションメッセージファイルを発見するメカニズムはやや複雑で、 LocaleMiddleware が必要になります。従って、このミドルウェアを使わない場 合、 Django メッセージファイルとプロジェクトメッセージファイルだけが処理さ れます。

最後に、翻訳ファイルをどのように構成するかしっかりと考えておくように勧めま す。自分の作ったアプリケーションを他のユーザに配ったり、他のプロジェクトで 利用したりするなら、アプリケーション固有の翻訳が必要になるでしょう。しかし、 アプリケーション固有のメッセージやプロジェクトごとの翻訳は makemessages にまつわる困った問題を引き起こすことがあります: makemessages は現在のパス以下の全てのディレクトリを検索してしまうので、 すでにアプリケーションメッセージファイルに入っているメッセージ ID が、プロ ジェクトのメッセージファイルに入ってしまうことがあるのです。

この問題の最も簡単な解決法は、プロジェクトを直接的に構築しない (なおかつ独 自の翻訳を備えている) アプリケーションをプロジェクトツリーの外に配置してお くというものです。こうすれば、プロジェクトレベルで django-admin.py make-messages を実行しても、自分のプロジェクトに明に関 係する部分の文字列だけを翻訳し、別個に配布されたアプリケーションの文字列を 対象にしなくなります。

set_language リダイレクトビュー¶

利便性のために、 Django には django.views.i18n.set_language ビューが定 義されています。このビューはユーザの言語プリファレンスを設定して、遷移前の ページにリダイレクトします。

このビューを有効にするには、以下の行を URLconf に追加します:

(r'^i18n/', include('django.conf.urls.i18n')),

(この例では /i18n/setlang/ でビューを使えるようにします)

ビューは、リクエストに language が設定された状態で、 POST メソッド で呼び出すようになっています。セッションのサポートが有効であれば、ビューは ユーザのセッションに選択した言語を保存します。セッションのサポートがなけれ ば、言語設定を django_language` クッキーに保存します。 (開発版の Django を使っているなら、クッキーの名前は LANGUAGE_COOKIE_NAME 設定で変更できます。)

選択された言語に設定した後、 Django は以下のアルゴリズムに従ってリダイレク トを行います:

• Django は POST データから next パラメタを探します。
• next がないか、空の値なら、 Referer ヘッダを使って遷移元を決 定しようとします。
• Referer の値も空の場合、例えばユーザのブラウザがリファラの送信を 抑制している場合には、フォールバックとして、ユーザは / (サイトの ルート URL) にリダイレクトします。

以下に HTML テンプレートのコード例を示します:

<form action="/i18n/setlang/" method="post">
<input name="next" type="hidden" value="/next/page/" />
<select name="language">
{% for lang in LANGUAGES %}
<option value="{{ lang.0 }}">{{ lang.1 }}</option>
{% endfor %}
</select>
<input type="submit" value="Go" />
</form>

翻訳と JavaScript¶

JavaScript に翻訳を追加しようとすると、いくつかの問題に直面します:

• JavaScript コードには gettext 実装へのアクセス手段がありません。
• JavaScript コードには .po や .mo ファイルへのアクセス手段がありません。 というのも、これらのファイルはサーバに置かれているからです。
• JavaScript の翻訳カタログはできるだけ小さくしておかねばなりません。

Django では、これらの問題に対する解決策を組み込みで提供しています。この解決 策は翻訳を JavaScript に渡して、 gettext などを JavaScript コード内で呼 び出せるようにします。

js_info_dict = {
    'packages': ('your.app.package',),
}

urlpatterns = patterns('',
    (r'^jsi18n/$', 'django.views.i18n.javascript_catalog', js_info_dict),
)

urlpatterns = patterns('',
    (r'^jsi18n/(?P<packages>\S+?)/$', 'django.views.i18n.javascript_catalog'),
)

<script type="text/javascript" src="/path/to/jsi18n/"></script>

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

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

function interpolate(fmt, obj, named);

s = interpolate(ungettext('this is %s object', 'this are %s objects', 11), [11]);

django-admin.py makemessages -d djangojs -l de

Django 翻訳の特徴¶

gettext について詳しければ、 Django の翻訳機能には以下のような特徴があ ることに気づくでしょう:

• 文字列ドメインは django または djangojs です。この文字列ドメ インは、共通のメッセージファイルライブラリ (通常は /usr/share/locale/ にあります) にデータを保存している他のプログラ ムと Django のデータを区別するためです。 django ドメインは、 Python とテンプレート翻訳文字列に使われ、グローバルな翻訳カタログ上に 読み込まれます。 djangojs は JavaScript だけで使うために、可能な かぎり小さくして分けてあります。
• Django は xgettext を単体では使いません。 Django では、 xgettext や msgfmt を Python ラッパ越しに使います。これは便宜 上の理由によります。

Windows で gettext を使う¶

この節の操作が必要なのは、 メッセージ ID を抜き出したり、メッセージファイル を (.po に) コンパイルしたいときだけです。翻訳の作業自体はファイルを編 集するだけですが、メッセージファイルを自分で作成したい場合や、変更したメッ セージファイルをテストしたりコンパイルしたい場合には、以下のようにして gettext ユーティリティを入れる必要があります:

• 以下の ZIP ファイルを http://sourceforge.net/projects/gettext から取得します:
  • gettext-runtime-X.bin.woe32.zip
  • gettext-tools-X.bin.woe32.zip
  • libiconv-X.bin.woe32.zip
• ダウンロードしたファイルを同じフォルダ (例えば C:\ProgramFiles\gettext-utils) に展開します。
• システム環境変数の PATH を変更します:
  • コントロールパネル > システム > 高度な設定 > 環境変数 の順に辿 ります。
  • システム環境変数 リストで、 Path を選び、 編集 を押しま す。
  • 変数値 フィールドの値の末尾に ;C:\Program Files\gettext-utils\bin を追加します。