概要

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を例にとります。

greeting-service_1.0.0.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に組み込むと、このようになります。

greeting-service_1.0.1.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