概要
IBM API Connect の開発者ポータルを多言語対応させる方法について、このところ立て続けに聞かれましたので、簡単にまとめてみました。作業の取っ掛かりになれば幸いです。
ここで言う多言語対応とは、ブラウザのLocaleやユーザーアカウントの設定によって開発者ポータルの表示言語を切り替えることを意図しています。開発者ポータルの多言語対応を考える場合、大きく分けて以下の2つの対応が必要です。
-
Drupalサイトの多言語対応
Drupalは多言語に対応していますので、コンテンツの翻訳リソースを用意していけば対応可能です。 -
API定義文書(Swagger)の多言語対応
Swagger2.0はそのままでは多言語対応していませんので、API定義文書を多言語対応するためにはベンダー拡張を利用します。
前提環境
本稿は執筆時点 (2017/12/15) のIBM Cloud環境を前提としています。オンプレミス版をご利用の場合はIBM API Connect v5.0.8.1が相当します。
Drupalサイトの多言語対応
Drupalサイトを多言語対応するためには、「翻訳」リソースを用意する必要があります。IBM API Connectの提供する開発者ポータルに初期状態で含まれているコンテンツの大半は日本語の翻訳リソースが付属していますが、不足している分についてはユーザーが追加することも可能です。
例えば、初期状態でメニューは以下のようになっています。
日本語と英語が混じっていて気持ち悪いので、日本語訳を追加してみます。
以下の作業はポータルの管理者としてログインした状態で行います。
サイト構築 > メニュー > メインメニュー を選択します。
メインメニュ―のアイテム一覧が表示されます。まずは Getting Started の 翻訳 を選択します。
各言語の翻訳リソース一覧が表示されます。Japanese のエントリを見ると Getting Started がそのまま訳として登録されてしまっているので、翻訳を選択して訳を修正します。
タイトルや説明を適宜修正し、 翻訳を保存 で変更内容を保存します。
他のメニュー項目についても同様に翻訳を修正し、ホームへ戻るとメニューの表示が更新されています。
API定義文書(Swagger)の多言語対応
IBM API Connect ではベンダー拡張である x-ibm-languages を使用することで多言語対応のための翻訳リソースを Swagger 文書内に挿入できます。x-ibm-languagesの使い方についての詳細はマニュアルの記述を参照してください。
例えば、以下のようなAPI製品YAMLを例にとります。
product: 1.0.0
info:
name: greeting-service
title: Greeting Service
version: 1.0.0
description: This service provides a set of greeting APIs.
visibility:
view:
enabled: true
type: public
tags: []
orgs: []
subscribe:
enabled: true
type: authenticated
tags: []
orgs: []
apis:
hello-api:
id: 5a33905d0cf236acd58e6cc0
plans:
Default:
title: Default Plan
このYAMLで定義されたAPI製品は、開発者ポータル上では以下のように表示されます。
x-ibm-languages を使うと、以下のように様々な要素に対する翻訳リソースを定義できます。
x-ibm-languages:
title:
ja: グリーティング・サービス
description:
ja: このサービスはグリーティングAPIを提供します。
API製品YAMLに組み込むと、このようになります。
product: 1.0.0
info:
name: greeting-service
title: Greeting Service
version: 1.0.0
description: This service provides a set of greeting APIs.
x-ibm-languages:
title:
ja: グリーティング・サービス
description:
ja: このサービスはグリーティングAPIを提供します。
visibility:
view:
enabled: true
type: public
tags: []
orgs: []
subscribe:
enabled: true
type: authenticated
tags: []
orgs: []
apis:
hello-api:
id: 5a33905d0cf236acd58e6cc0
plans:
Default:
title: Default Plan
改めて開発者ポータルの画面を表示すると、画面が無事に翻訳されています。
ブラウザの言語設定を変更して、Accept-Languageヘッダーをen優先にするとこのように英語表示に切り替わります。
言語判定ルールの変更方法
開発者ポータルの表示言語の判定ルールは、デフォルトでは以下の優先順位となっています。
- ログイン・ユーザー毎のプロファイルで指定された言語
- ブラウザの言語
これらの定義はDrupalサイトの構成定義によって制御することが可能です。
構成 > 地域と言語 > 言語 > 判定と選択 を選択して 言語の判定 画面へアクセスします。
ユーザーインターフェーステキスト 言語の判定 の設定によって判定ルールの優先順位や詳細を定義することが可能です。
また コンテンツ 言語の判定 はデフォルトでは インターフェース に設定されていますので、コンテンツの言語判定はユーザーインターフェースの判定に従います。コンテンツとユーザーインターフェース (フレーム、タイトル、ヘルプ等) で異なる言語を使いたい場合はこちらを変更します。
ユーザーインターフェース、コンテンツなどDrupal Coreが提供する言語タイプについてはDrupalのマニュアル (Language Negotiation API) をご参照ください。