国際化

国際化のサポートは必須機能です。

— Jannis Leidel、Django Under the Hood 2015での講演より.

REST frameworkには、翻訳可能なエラーメッセージが付属しています。Djangoの標準的な翻訳メカニズムを有効にすることで、これらのメッセージを任意の言語で表示できます。

これにより、以下が可能になります。

標準のLANGUAGE_CODE Django設定を使用して、英語以外の言語をデフォルト言語として選択します。
Djangoに含まれるLocaleMiddlewareを使用して、クライアントが自身で言語を選択できるようにします。APIクライアントの典型的な使用方法としては、Accept-Languageリクエストヘッダーを含めることが挙げられます。

国際化されたAPIの有効化

標準のDjangoのLANGUAGE_CODE設定を使用して、デフォルト言語を変更できます。

LANGUAGE_CODE = "es-es"

MIDDLEWARE設定にLocalMiddlewareを追加することで、リクエストごとの言語要求を有効にできます。

MIDDLEWARE = [
    ...
    'django.middleware.locale.LocaleMiddleware'
]

リクエストごとの国際化が有効になっている場合、クライアントのリクエストは可能な限りAccept-Languageヘッダーを尊重します。例えば、サポートされていないメディアタイプのリクエストを行うとします。

リクエスト

GET /api/users HTTP/1.1
Accept: application/xml
Accept-Language: es-es
Host: example.org

レスポンス

HTTP/1.0 406 NOT ACCEPTABLE

{"detail": "No se ha podido satisfacer la solicitud de cabecera de Accept."}

REST frameworkには、標準的な例外ケースとシリアライザーのバリデーションエラーの両方に対して、これらの組み込み翻訳が含まれています。

翻訳はエラー文字列自体にのみ適用されることに注意してください。エラーメッセージの形式とフィールド名のキーは同じままです。例として、400 Bad Requestレスポンスボディは次のようになります。

{"detail": {"username": ["Esse campo deve ser único."]}}

detailやnon_field_errorsなどのレスポンスの一部に異なる文字列を使用したい場合は、カスタム例外ハンドラーを使用してこの動作を変更できます。

サポートされる言語セットの指定。

デフォルトでは、利用可能なすべての言語がサポートされます。

利用可能な言語のサブセットのみをサポートする場合は、Djangoの標準的なLANGUAGES設定を使用します。

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

新しい翻訳の追加

REST frameworkの翻訳は、Transifexを使用してオンラインで管理されています。Transifexサービスを使用して、新しい翻訳言語を追加できます。メンテナンスチームは、これらの翻訳文字列がREST frameworkパッケージに含まれるようにします。

ローカルでプロジェクトに翻訳文字列を追加する必要がある場合があります。これは、以下の場合に必要になる可能性があります。

Transifexでまだ翻訳されていない言語でREST Frameworkを使用したい場合。
プロジェクトにREST frameworkのデフォルトの翻訳文字列に含まれていないカスタムエラーメッセージが含まれている場合。

新しい言語をローカルで翻訳する

このガイドでは、Djangoアプリの翻訳方法を既に知っていることを前提としています。そうでない場合は、Djangoの翻訳ドキュメントから始めましょう。

新しい言語を翻訳する場合は、既存のREST frameworkエラーメッセージを翻訳する必要があります。

国際化リソースを保存する新しいフォルダを作成します。このパスをLOCALE_PATHS設定に追加します。
次に、翻訳する言語のサブフォルダを作成します。フォルダ名はロケール名表記法を使用する必要があります。例：de、pt_BR、es_AR。
次に、REST frameworkソースコードから基本的な翻訳ファイルを翻訳フォルダにコピーします。
コピーしたdjango.poファイルを編集し、すべてのエラーメッセージを翻訳します。
manage.py compilemessages -l pt_BRを実行して、Djangoで使用できる翻訳を作成します。「processing file django.po in <...>/locale/pt_BR/LC_MESSAGES」のようなメッセージが表示されるはずです。
変更を有効にするために、開発サーバーを再起動します。

プロジェクトのコードベース内にあるカスタムエラーメッセージのみを翻訳する場合は、REST frameworkソースのdjango.poファイルをLOCALE_PATHSフォルダにコピーする必要はなく、代わりにDjangoの標準的なmakemessagesプロセスを実行するだけです。

言語の決定方法

リクエストごとの言語設定を許可する場合は、MIDDLEWARE設定にdjango.middleware.locale.LocaleMiddlewareを含める必要があります。

言語設定の決定方法の詳細については、Djangoのドキュメントを参照してください。参考までに、その方法は次のとおりです。

最初に、要求されたURLから言語プレフィックスを探します。
それが失敗した場合は、現在のユーザーのセッションからLANGUAGE_SESSION_KEYキーを探します。
それが失敗した場合は、Cookieを探します。
それが失敗した場合は、Accept-Language HTTPヘッダーを確認します。
それが失敗した場合は、グローバルなLANGUAGE_CODE設定を使用します。

APIクライアントにとって、最も適切な方法は通常、Accept-Languageヘッダーを使用することです。セッション認証を使用しない限り、セッションとCookieは使用できず、一般的に、言語URLプレフィックスを使用するよりも、APIクライアントでAccept-Languageヘッダーを優先する方が良い方法です。