ローカライズされたデータ、コード一覧、および共通の再利用タイプの使用

このレッスンでは、テキストアプリケーションデータの翻訳を提供する方法について説明します。たとえば、本のタイトルをさまざまな言語で更新する必要があります。

最初に、ローカライズされたデータを宣言する方法について説明します。

localized 修飾子は、ローカライズされたデータを宣言するために使用されます。これを使用して、翻訳済テキストが必要なエンティティエレメントを特定します。以下の図では、Books エンティティの title エレメントが適宜マークされています。

前述の定義に基づき、さまざまなものがCDSコンパイラによって自動的に生成される。特に、翻訳済テキストを保持するために個別の Books.texts エンティティが生成されます。このエンティティの構造は以下のとおりです。

12345
entity Books.texts {
  key locale : sap.common.Locale;
  key ID     : UUID;
      title  : String(255);
}

Books.texts エンティティには、ロケールと ID の 2 つのキー項目があります。

キー項目ロケールのデータ型は sap.common.Locale です。これは、前述の @sap/cds/common モデルの共通の再利用タイプです。最終的に、このタイプは、長さ 14 の文字列を定義するために使用されます。地域情報フィールドは、en や de などの言語コードを保存することを目的としています。

2 番目のキー項目 ID は、ブックエンティティの一次キーに対応します。

Books.texts エンティティを使用すると、各言語コード (ロケール) の翻訳済みタイトルを各ブック (つまり、各 ID) に保存することができます。

ローカライズされたテキストを読み込むために、Books.texts エンティティのほかに、生成された SQL DDL を使用して追加ビューも登録されます。

サービスランタイムの一般ハンドラは、生成されたビューを使用して、ユーザの優先言語で読込要求を自動的に処理します。この例では、ブックタイトルが優先言語で自動的に受信されます。この言語の翻訳がない場合は、代替言語で送信されます。このタイトルは、Books エンティティに属するテーブルに格納されるタイトルになります。

URL パラメータ sap-locale を使用して、さまざまな言語をテストできます。以下の例では、ドイツ語のテキストが要求されています。

1
GET <your_service_url>/Books?sap-locale=de

または、適切な Accept-Language ヘッダで要求を使用することもできます。

12
GET <your_service_url>/Books
 Accept-Language: de

URL パラメータ sap-locale の優先度が最も高くなります。これを設定する必要がある場合は、Accept-Language ヘッダが上書きされます。

次に、ローカライズされたデータをアプリケーションで最初に利用可能にする方法について見ていきましょう。

初期データを追加する方法については、ビデオを視聴してください。

以下のセクションでは、@sap/cds/common モデルの CodeList アスペクトと Country および Currency のタイプについて説明します。

ここでは、CAP によって提供されるコード一覧のコンセプトについて説明します。翻訳可能な値一覧を提供する標準化された方法が提供されます。

コード一覧の概要については、ビデオを視聴してください。

次に、コード一覧の使用方法を見ていきましょう。

sap.common.CodeList アスペクトは、CAP のコード一覧の基本定義を提供します。これは @sap/cds/common モデルに属しています。名称領域 sap.common は、context ディレクティブを使用して設定されます (以下の図を参照)。このディレクティブは、定義内のネストされた名前空間セクションに使用されます。

アスペクト sap.common.CodeList は、前述の localized 修飾子でマークされた 2 つのエレメント name と descr を定義します。これにより、すでに説明したように、これらの項目に翻訳済テキストを提供することができます。

前の定義で使用されるアノテーションのうち、アノテーション @cds.autoexpose はここで特に重要です。後で Epochs と呼ばれる独自のコード一覧をエンティティの形式で実装し、sap.common.CodeList で拡張します。つまり、Epochs エンティティは sap.common.CodeList から @cds.autoexpose を継承します。その結果、Epochs コード一覧エンティティは、Epochs エンティティへのアソシエーションがあるエンティティを含むサービスに自動的に公開されます。このシナリオでは、Authors エンティティによって Epochs エンティティへのこのようなアソシエーションが定義されます。つまり、SAP 側での追加のアクションなしで、生成された OData サービスで Epochs エンティティのエンティティセットが公開されます。

独自のコード一覧を登録するには、sap.common.CodeList ディレクティブを使用して @sap/cds/common モデルから using アスペクトをインポートします。以下の図の例では、これは using の ES6 型デコンストラクタバリアントを使用して行われます。

この例では、CodeList アスペクトがインクルードとして使用され、Epochs エンティティが適宜拡張されます。エンティティの構造は、最終的に以下のようになります。

12345
entity Epochs {
  key ID    : Integer;
      name  : localized String(255);
      descr : localized String(1000);
}

localized 修飾子に関する説明から、cds コンパイラは翻訳されたテキストを保持するために先行する定義に基づいて個別の Epochs.texts エンティティを生成することがわかっています。このエンティティには、各 ID の言語コード (ロケール) の名前と説明の翻訳を保存できるように、以下の定義があります。

123456
entity Epochs.texts {
  key locale : sap.common.Locale;
  key ID     : Integer;
      name   : String(255);
      descr  : String(1000);
}

コード一覧については、本のタイトルの説明と同じ方法で初期データを提供することができます。これを行うには、最初にデフォルト言語のすべてのデータを含む .csv ファイルが必要です。

このシナリオでは、これは com.sap.learning-Epochs.csv ファイルです。このファイルのエントリは以下のようになります。この例では、名称のみが更新され、内容説明はデフォルト言語の英語で更新されません。

アプリケーションでサポートされる他の言語への翻訳は、対応する 2 つ目の .csv ファイルを使用して作成することができます。この例では、このファイルはファイル com.sap.learning-Epochs.texts.csv です。このファイルのエントリは、エポック名のドイツ語翻訳を提供するために以下のように表示されます。

Authors エンティティの Epochs コード一覧を使用して、エポックを作成者に割り当てます。これを行うには、以下の図に示すように、Authors エンティティから Epochs エンティティへのエポックという管理対象 1 アソシエーションを作成します。

この管理対象 1 アソシエーションの期間が CAP によってどのように実現されるかが分かっています。Epochs コード一覧にはキー項目 ID があるため、Authors エンティティ用に生成されたデータベーステーブルに epoch_ID という外部キー項目が作成されます。

1234
CREATE TABLE com_sap_learning_Authors (
   ...
  epoch_ID INTEGER
);

この外部キー項目は、作成者と、それが割り当てられているデータベース上のエポックとの関係を保存するために使用されます。

国、通貨、および言語に対して、CAP では @sap/cds/common モデルを介して事前定義されたコード一覧 sap.common.Countries、sap.common.Currencies、および sap.common.Languages が提供されます。

ただし、独自のモデルでは、これらのコード一覧を直接参照することはほとんどありません。代わりに、これらのコード一覧への対応するアソシエーションを定義する @sap/cds/common モデルに含まれる再利用タイプ Country、Currency、および Language も使用します。

以下のセクションでは、Country および Currency タイプの使用方法について詳しく説明します。言語の詳細については、CAP 文書を参照してください。

共通の再利用タイプ Country は、以下の図に示すように、@sap/cds/common でコード一覧エンティティ sap.common.Countries への管理対象 1 のアソシエーションとして定義されています。

コード一覧エンティティ sap.common.Countries は、ISO 3166-1 の 2 文字の英字コードを一次キーとして使用することを目的としています。つまり、たとえばドイツの場合、対応するキー項目コードに値 "DE" が含まれます。

sap.common.CodeList がインクルードとして使用される sap.common.Countries エンティティの先行定義により、最終的にインクルードを解決することによって以下の構造のエンティティになります。

12345
entity sap.common.Countries {
  key code  : String(3);
      name  : localized String(255);
      descr : localized String(1000);
}

次に、cds コンパイラは、すでに説明したように、翻訳されたテキストを保持するために、別の sap.common.Countries.texts エンティティを生成します。このエンティティには、各国 (コード) の言語コード (ロケール) の名前と説明の翻訳を保存できるように、以下の定義があります。

123456
entity sap.common.Countries.texts {
  key locale : sap.common.Locale;
  key code   : String(3);
      name   : String(255);
      descr  : String(1000);
}

共通の再利用タイプ Currency は、タイプ Country と同様に定義されます。これにより、コード一覧エンティティ sap.common.Currencies への管理対象 1 アソシエーションが指定されます。

コード一覧エンティティ sap.common.Currencies は、ISO 4217 の 3 文字の英字コードを一次キーとして使用することを目的としています。つまり、対応するキー項目コードには、たとえば、US ドルを表す "USD" が含まれます。また、このコード一覧には、共通通貨記号のエレメントと補助単位のエレメントが小数点以下桁数形式で含まれています。

sap.common.CodeList がインクルードとして使用されているエンティティ sap.common.Currencies の前の定義では、最終的にインクルードを解決することで、以下の構造のエンティティになります。

1234567
entity sap.common.Currencies {
  key code      : String(3);
      symbol    : String(5);
      minorUnit : Int16;
      name      : localized String(255);
      descr     : localized String(1000);
}

また、cds コンパイラは、翻訳されたテキストを保持するための個別のエンティティ sap.common.Currencies.texts も作成します。このエンティティには、各通貨 (コード) の言語コード (ロケール) の名前と説明の翻訳を保存できるように、以下の定義があります。

123456
entity sap.common.Currencies.texts {
  key locale    : sap.common.Locale;
  key code      : String(3);
      name      : String(255);
      descr     : String(1000);
}

国および通貨コード一覧の初期データを提供するには、db/data ディレクトリに以下の .csv ファイルを作成します。

以下の図は、国コード一覧の 2 つのファイルの例を示しています。簡略化のため、ここではテキスト項目は更新されません。ファイル sap.common-Countries.texts.csv には、sap.common-Countries.csv からの国名のドイツ語翻訳が含まれています。

したがって、以下の例は、通貨コード一覧の 2 つのファイルを示しています。ここでは、コード、名称、およびシンボル項目のみが更新されます。通貨名の翻訳は必要ありません。そのため、sap.common-Currencies.texts.csv ファイルには列タイトルのみが含まれており、翻訳エントリは含まれません。

上記の Country タイプと Currency タイプを使用できるようにするには、以下の図に示すように using ディレクティブを使用してインポートします。

sap.common.Countries および sap.common.Currencies コード一覧へのアソシエーションを最終的に定義するために、インポートされたタイプを定義の対応するエレメントに割り当てます。

この例では、Books エンティティの publCountry エレメントのデータ型は Country であるため、sap.common.Countries コード一覧へのアソシエーションが実装されます。これに応じて、Books エンティティの価格要素の通貨コンポーネントによって、sap.common.Currencies コード一覧へのアソシエーションが定義されます。

割り当てられたタイプにより、エレメント publicCountry および price_currency は、生成された OData サービスのナビゲーションプロパティになります。

publCountry および price_currency のナビゲーションターゲット (コード一覧エンティティ sap.common.Countries および sap.common.Currencies) は、基本タイプ sap.common.CodeList の @cds.autoexpose アノテーションにより、OData サービスでエンティティセットとして自動的に公開されます。上記の動作については、Authors エンティティのエポックエレメントの例を使用してすでに説明しています。このナビゲーションプロパティは、ユーザ定義の Epochs コード一覧へのアソシエーションとして実装されました。

コード一覧へのアソシエーションは、対応する外部キー項目を介してブックエンティティに対して生成されたデータベーステーブルで実現されます。sap.common.Countries コード一覧にはキー項目コードがあるため、PublicCountry_code という外部キー項目が Books エンティティ用に生成されたデータベーステーブルに登録されます。それに応じて、外部キー項目 price_currency_code が sap.common.Currencies コード一覧へのアソシエーションに対して登録されます。

12345
CREATE TABLE com_sap_learning_Books (
   ...
  publCountry_code NVARCHAR(3),
  price_currency_code NVARCHAR(3)
);

外部キー項目は、帳簿と割当済発行国の関係、および割り当てられた通貨をデータベースに保存するために使用されます。

ビデオを視聴して、ローカライズされたデータ、コード一覧、および共通の再利用タイプを使用する方法を確認してください。