FlaskでJSONレスポンスを多言語化！API設計の基本を初心者向けに解説

1. APIとJSONレスポンスとは何かを知ろう

1. APIとJSONレスポンスとは何かを知ろう

まずは、今回扱う用語の意味から整理しましょう。「API（エーピーアイ）」とは、プログラム同士が情報をやり取りするための専用の窓口のようなものです。例えば、スマートフォンのアプリがサーバーから最新のニュースを取得するときなどに使われます。

その窓口でやり取りされるデータの形式で、最も一般的なのが「JSON（ジェイソン）」です。これは、情報を「名前」と「値」のセットで表現する書き方です。例えば、「メッセージ：こんにちは」という情報を、コンピュータが扱いやすいようにカッコで囲って表現します。

「レスポンス」というのは、APIにお願いをしたときに返ってくるお返事のことです。多言語化とは、このお返事の内容を、日本人には日本語で、アメリカ人には英語で返す仕組みを作ることを指します。Webアプリを世界展開するなら、避けては通れない大切な技術です。

2. 多言語化に必要なFlask-Babelの準備

2. 多言語化に必要なFlask-Babelの準備

Pythonで多言語対応を行うには、「Flask-Babel（フラスク・バベル）」という拡張機能を使うのが一番の近道です。これは、プログラムの中に書かれた特定の言葉を、あらかじめ用意しておいた翻訳リスト（辞書）から探し出して置き換えてくれる便利な道具です。

パソコンにこの道具を入れるには、コマンド画面で以下の命令を入力します。インストールという作業ですね。

pip install Flask-Babel

インストールが終わったら、プログラムの中で初期設定を行います。これにより、Flaskという枠組みの中で翻訳機能が使えるようになります。パソコン初心者の方は、まず「翻訳専用の部品を組み込むんだな」と考えていただければ問題ありません。設定が終われば、いよいよ具体的な設計に入ります。

3. 相手がどの言語を求めているか判断する仕組み

3. 相手がどの言語を求めているか判断する仕組み

APIに対して「英語で返してほしい」というリクエストを伝えるには、いくつかの方法があります。最も一般的なのは、インターネットの通信に付随する「ヘッダー」という情報の中に、希望する言語を書き込む方法です。これを「Accept-Language」ヘッダーと呼びます。

Flask-Babelを使うと、このヘッダー情報を自動的に読み取って、最適な言語を選んでくれる関数を作ることができます。以下のコードを見てみましょう。

from flask import Flask, request, jsonify
from flask_babel import Babel, _

app = Flask(__name__)
babel = Babel(app)

# どの言語を使うかを決める設定です
@babel.localeselector
def get_locale():
    # ブラウザやアプリが送ってきた言語設定を確認して、最適なもの（jaかen）を選びます
    return request.accept_languages.best_match(['ja', 'en'])

このコードにある localeselector という部分が、言語選びの司令塔になります。これにより、日本語を優先している人には日本語を、そうでない人には英語を返すという判断が自動的に行われるようになります。プログラムが賢く動くための最初のステップですね。

4. JSONでお返事するメッセージを翻訳可能にする

4. JSONでお返事するメッセージを翻訳可能にする

次に、実際にお返事（レスポンス）として返すメッセージを翻訳できるように書き換えます。やり方はとても簡単で、翻訳したい言葉を _() という記号で囲むだけです。これは「アンダースコア」と呼ばれる記号で、翻訳の魔法の杖だと思ってください。

@app.route('/api/hello')
def hello():
    # 普通に返すと「こんにちは」だけですが、_() で囲むと翻訳対象になります
    message = _('こんにちは、世界！')
    
    # jsonifyは、データをJSON形式に整えてくれる命令です
    return jsonify({
        'status': 'success',
        'message': message
    })

この _('こんにちは、世界！') と書かれた部分は、後で作成する「翻訳辞書」と照らし合わされます。英語の設定でアクセスが来ると、ここが自動的に「Hello, World!」に化けるというわけです。プログラム本体を何種類も作る必要がないので、とても効率的ですね。

5. 翻訳辞書ファイルを作成する手順

5. 翻訳辞書ファイルを作成する手順

言葉を翻訳するには、対応表となる「辞書ファイル」が必要です。このファイルは、人間が手作業で翻訳後の言葉を書き込んでいく場所です。作業の流れは「抽出」「作成」「コンパイル」の三段構えになります。

まず、プログラムの中から _() で囲まれた言葉を抜き出し、翻訳用の型紙を作ります。次に、その型紙を元に、例えば「日本語用」や「英語用」のファイル（.poファイルといいます）を作成します。そのファイルを開くと、翻訳前の言葉が並んでいるので、その横に翻訳後の言葉を記入します。

最後に、そのファイルをコンピュータが読みやすい形式（.moファイル）に変換します。これを「コンパイル」と言います。初心者の方は、このコンパイル作業を忘れがちなので注意しましょう。この手順を踏むことで、初めてプログラムが多言語でおしゃべりできるようになります。

6. エラーメッセージも多言語化して親切なAPIに

6. エラーメッセージも多言語化して親切なAPIに

成功したときのメッセージだけでなく、入力ミスがあったときなどのエラーメッセージも多言語化しておくと、使う人にとって非常に親切なAPIになります。例えば、数字が必要な場所に文字が入っていた場合の警告メッセージなどです。

@app.route('/api/data', methods=['POST'])
def receive_data():
    data = request.get_json()
    
    if not data:
        # データが空っぽだったときのエラーメッセージを翻訳します
        error_msg = _('データが送信されていません。')
        return jsonify({'error': error_msg}), 400
        
    return jsonify({'result': _('データを受理しました。')})

このように、あらゆる場面で _() を活用することで、世界中の開発者が使いやすいAPIへと進化させることができます。エラーの意味が自分の国の言葉で表示されると、開発もスムーズに進みますよね。おもてなしの心をプログラムにも込めることができるのです。

7. 文字化けを防ぐための大事なルール

7. 文字化けを防ぐための大事なルール

多言語化、特に日本語を扱うときに気をつけなければならないのが「文字化け」です。文字化けとは、せっかく書いた日本語が、わけのわからない記号の羅列になってしまう現象です。これを防ぐには、ファイルを保存するときの「文字コード」という設定を必ず「UTF-8」にする必要があります。

また、Flaskの設定で JSON_AS_ASCII という項目を「False」に設定しておくことも推奨されます。デフォルト（初期設定）のままだと、日本語が特別な記号に変換されてしまうことがありますが、この設定をオフにすることで、綺麗な日本語のまま表示されるようになります。

パソコンの操作に不慣れなうちは、こうした細かい設定でつまずくことが多いですが、「日本語を扱うときはUTF-8にする」というルールさえ守れば、大きなトラブルは避けられます。丁寧に進めていきましょう。

8. 翻訳が正しく動いているか確認する方法

8. 翻訳が正しく動いているか確認する方法

設定がすべて終わったら、実際にテストをしてみましょう。ブラウザの言語設定を変えてみるのも一つの手ですが、APIのテストには「Postman」や「Talend API Tester」といった専用のツールを使うと便利です。

リクエストを送る際に、「Accept-Language」という項目に「en」と入力して送信してみましょう。もしお返事のメッセージが英語に変わっていれば成功です。逆に「ja」と入れれば日本語が返ってくるはずです。

（送信するヘッダーの例）
Accept-Language: en

（返ってくるJSONの例）
{
  "message": "Hello, World!",
  "status": "success"
}

自分の書いたコードが、相手の要望に合わせて言葉を変えてお返事する様子を見ると、プログラミングの面白さを実感できるはずです。一度仕組みを作ってしまえば、あとは新しい言葉を辞書に追加していくだけで、いくらでも対応言語を増やすことができますよ。