文字列のローカライズとメッセージ・ディクショナリ
このページでは、インターシステムズ製品における文字列のローカライズの概要と、メッセージ・ディクショナリをエクスポート、インポート、および管理する方法を説明します。
文字列のローカライズ
アプリケーションのテキストをローカライズする場合、ある言語のテキスト文字列のインベントリを作成してから、アプリケーションのロケールが異なるときに別言語の変換バージョンのメッセージに置き換える規約を設定します。
インターシステムズ製品は、文字列をローカライズするために以下のプロセスをサポートします。
-
開発者が、ローカライズ可能な文字列をコード内 (REST アプリケーションまたはビジネス・インテリジェンス・モデル内) に含めます。
このメカニズムはさまざまですが、最も一般的なメカニズムは $$$Text マクロです。ハードコードされたリテラル文字列の代わりに、$$$Text マクロのインスタンスを記述して、マクロ引数の値を以下のように指定します。
-
既定の文字列
-
この文字列の所属先のドメイン (文字列がドメインにグループ化されている場合、ローカライズの管理が簡単になります)
-
既定の文字列の言語コード
例えば、以下を指定するのではなく、
write "Hello world"
以下を記述します。
write $$$TEXT("Hello world","sampledomain","en-us")
-
-
コードをコンパイルすると、コンパイラによって、$$$Text マクロの一意のインスタンスごとに、メッセージ・ディクショナリにエントリが生成されます。
メッセージ・ディクショナリはグローバルであるため、(例えば) 管理ポータルで簡単に確認できます。一般的なタスクに役立つクラス・メソッドがいくつかあります。
-
開発が完了したら、リリース・エンジニアは、対象のドメインまたはすべてのドメインのメッセージ・ディクショナリをエクスポートします。
結果は、元の言語でのテキスト文字列を含む 1 つ以上の XML メッセージ・ファイルになります。
-
リリース・エンジニアは、これらのファイルをトランスレータに送信し、変換されたバージョンを要求します。
-
トランスレータは、好みの XML オーサリング・ツールを使用して XML メッセージ・ファイルで作業します。基本的には、前後の XML を変更することなく、テキストを元の言語から新しい言語に変換します。
-
トランスレータは、同じ構造を持つ以下のような新しい XML メッセージ・ファイルを返します。
-
<MsgFile> 要素の language 属性の RFC1766Opens in a new tab 値を識別する
-
識別された言語の変換済みテキストを格納する
-
-
リリース・エンジニアは、変換された XML メッセージ・ファイルを、元のファイルのエクスポート元である同じネームスペースにインポートします。
メッセージ・ディクショナリに、変換されたテキストと元のテキストが共存します。
-
実行時に、アプリケーションは、ブラウザの既定の言語に基づいてどのテキストを表示するかを選択します。
手順 1 と 2 の詳細は、以下の章を参照してください。
-
"InterSystems IRIS Business Intelligence の実装" の “ローカライズの実行”
このページの以降の部分では、メッセージ・ディクショナリの管理について説明します。
メッセージ・ディクショナリ
メッセージ・ディクショナリは、ドメイン名、言語名、およびメッセージ ID で編成されたテキスト文字列が含まれるグローバルです。
-
各メッセージのテキストは最大 32K 文字の文字列です。データベースで長い文字列が有効になっている場合は、これよりも長い文字列にできますが、既定の最大値は 32K です。メッセージはテキストのみで構成することも、%1、%2 などによって指定したパラメータを 1 つ以上含めることもできます。そのメッセージをアプリケーションのページに表示する必要がある場合、これらのパラメータをテキスト (エラー・メッセージ内のファイル名など) に置換できます。
-
ドメイン名は任意の文字列です。これは、特定のアプリケーションやページのすべてのメッセージなど、関係があるテキスト項目のグループを識別します。メッセージのセットにドメインを割り当てると、後から同じドメインを持つすべてのメッセージに特定の操作を実行できます。
ドメイン名では大文字と小文字が区別され、大文字と小文字を含めることができます。ドメイン名が % で始まる場合は、そのドメイン内にあるすべてのメッセージは、あらゆるネームスペースで表示されるシステム・メッセージと見なされます。そうでない場合、作成したメッセージは、そのメッセージが定義されたネームスペースでのみ表示されます。
-
言語名は、RFC1766Opens in a new tab に従うすべて小文字の言語タグです。これは、1 つ以上の部分で構成されます。つまり、主言語タグ (en や ja) の後に、オプションでハイフン (-) で区切られた 2 番目の言語タグを (en-gb や ja-jp) 記述します。
-
メッセージ ID は任意の文字列で、メッセージを一意に識別します。メッセージ ID はドメイン内でのみ一意である必要があります。ユーザがメッセージ ID を割り当てることも、メッセージの作成に使用した規約に応じてコンパイラで割り当てることもできます。メッセージ ID では大文字と小文字が区別され、大文字と小文字を含めることができます。
メッセージ・ディクショナリの格納
各ユーザ定義ネームスペースは、そのメッセージ・ディクショナリを ^IRIS.Msg という添え字付きグローバルに格納します。^IRIS.Msg の添え字の順序は、ドメイン、言語、およびメッセージ ID です。
ネームスペースの ^IRIS.Msg を表示するには、以下の手順に従います。
-
管理ポータルを起動します。
-
目的のネームスペースに切り替えます。
-
[システム・エクスプローラ]→[グローバル] をクリックします。
-
[IRIS.Msg] の行で、[表示] をクリックします。
例を以下に示します。
^IRIS.Msg("mydomain")="en" ^IRIS.Msg("mydomain","en",338288369)="sample string" ^IRIS.Msg("mydomain","en",3486914925)="another sample string"
XML メッセージ・ファイル
XML メッセージ・ファイルは、メッセージ・ディクショナリをエクスポートしたものです。また、インポートするメッセージで必要な形式でもあります (エクスポートとインポートの手順は、“メッセージ・ディクショナリの管理” のセクションを参照してください)。
可能であれば、XML メッセージ・ファイルでは UTF-8 エンコードを使用する必要があります。ただし、場合によっては、開発者またはトランスレータは、shift-jis などのローカル・プラットフォームのエンコーディングを使用して、XML メッセージ・ファイルを容易に編集できるようにすることができます。XML ファイルに使用するエンコーディングはすべて、アプリケーションのロケールでサポートされている必要があります。また、その言語のメッセージを表すことができる必要があります。
1 つの XML メッセージ・ファイルには 1 つの言語と複数のドメインのメッセージを含めることができます。
<MsgFile> 要素
<MsgFile> 要素は、XML メッセージ・ファイルの最上位コンテナで、1 つのファイルに存在する <MsgFile> 要素は 1 つだけです。
<MsgFile> 要素には 1 つの必須属性 Language があります。<MsgFile> の Language 属性の値は、すべて大文字の RFC1766Opens in a new tab コードであり、ファイルの言語を識別します。 これは、1 つ以上の部分で構成されます。つまり、主言語タグ (en や ja) の後に、オプションでハイフン (-) で区切られた 2 番目の言語タグを (en-gb や ja-jp) 記述します。
以下の例では、この言語は "en" (英語) です。
<?xml version="1.0" encoding="utf-8" ?>
<MsgFile Language="en">
<MsgDomain Domain="sample">
<Message Id="source">Source</Message>
<Message Id="menu">Samples Menu</Message>
</MsgDomain>
</MsgFile>
<MsgFile> には <MsgDomain> 要素が少なくとも 1 つ含まれる必要があります。複数の <MsgDomain> を含めることができます。
<MsgDomain> 要素
<MsgDomain> 要素には 1 つの必須属性 Domain があります。<MsgDomain> の Domain 属性の値は、アプリケーションのメッセージを編成するために使用しているドメイン名の 1 つです。
<MsgDomain> 要素には、0 個以上の <Message> 要素を含めることができます。
<Message> 要素
<Message> 要素には 1 つの必須属性 Id があります。<Message> の Id 属性の値は、アプリケーションのメッセージを編成するために使用しているメッセージ ID 文字列の 1 つです。
<Message> 要素にはテキスト文字列を含めることができます。文字列は、以下の項目を個別に構成するか、組み合わせて構成することができます。
-
使用可能なファイル形式のシンプル・テキスト
-
置換引数 %1、%2、%3、または %4
-
HTML 形式
-
ObjectScript 形式の文字列表現
以下の例では、%1、%2、太字書式の HTML タグ、および連続する 2 つの二重引用符は 1 つの二重引用符を示すという ObjectScript の文字列規約を使用しています。
<Message>
The session $Username="<b>%1</b>" $Roles="<b>%2</b>"
</Message>
メッセージ・ディクショナリの管理
このセクションでは、メッセージ・ディクショナリを操作する際に最もよく使用される %Library.MessageDictionaryOpens in a new tab メソッドを簡単に説明します。これらのメッセージを使用すると、以下のことができます。
-
XML メッセージ・ファイルからメッセージをインポートする
-
XML メッセージ・ファイルへメッセージをエクスポートする
-
メッセージ・ディクショナリからメッセージを削除する
-
メッセージ・ディクショナリ内のメッセージをリストする
XML メッセージ・ファイルのインポート
XML メッセージ・ファイルをインポートするには、ターミナルを開いて以下の操作を行います。
-
アプリケーションを開発しているネームスペースに変更します。
set $namespace = "myNamespace"
-
import コマンドを実行します。既定では、各言語は別個の XML メッセージ・ファイルになっており、ファイル名の末尾にロケール名が付いています。したがって、以下のようになります。
-
特定の言語のメッセージのみをインポートできます。
SET file="C:\myLocation\Messages_ja-jp.xml" DO ##class(%Library.MessageDictionary).Import(file)
-
または、同じアプリケーションに対して複数の言語をインポートします。
SET myFiles="C:\myLocation" DO ##class(%Library.MessageDictionary).ImportDir(myFiles,"d")
-
-
同じネームスペース内の ^IRIS.Msg グローバルを調べて結果を確認します。
以下のトピックでは、両方のインポート方法を簡単に説明します。
特定の XML メッセージ・ファイルのインポート
%Library.MessageDictionaryOpens in a new tab クラス・メソッド Import() には以下のシグニチャがあります。
classmethod Import(filepath As %String, flag As %String = "") returns %Status
引数 | 説明 |
---|---|
filepath | filepath で指定された XML メッセージ・ファイルをインポートします。XML メッセージ・ファイルのみがディレクトリ内にあることを確認してください。他の XML ファイルがあるとエラーが生成されます。 |
flag | (オプション) d フラグ (display) を指定した場合、ファイルのインポート時にターミナル・コンソールに確認メッセージが表示されます。指定しない場合、確認は表示されません。 |
ディレクトリ内にあるすべての XML メッセージ・ファイルのインポート
%Library.MessageDictionaryOpens in a new tab クラス・メソッド ImportDir() には以下のシグニチャがあります。
classmethod ImportDir(directory As %String, flag As %String = "") returns %Status
引数 | 説明 |
---|---|
directory | 指定したディレクトリ内にあるすべての XML メッセージ・ファイルをインポートします。 |
flag | (オプション) d フラグ (display) を指定した場合、ファイルのインポート時にターミナル・コンソールに確認メッセージが表示されます。指定しない場合、確認は表示されません。 |
XML メッセージ・ファイルのエクスポート
メッセージ・ディクショナリを XML メッセージ・ファイルにエクスポートするには、ターミナル内で以下の操作を行います。
-
アプリケーションを開発しているネームスペースに変更します。
set $namespace = "myNamespace"
-
出力ファイルとその場所を特定します。
SET file="C:\myLocation\Messages.xml"
-
export コマンドを実行します。
-
特定のドメインにあるメッセージのみをエクスポートすることが実際的な場合があります。この場合は次のように指定します。
DO ##class(%Library.MessageDictionary).ExportDomainList(file,"myDomain")
-
ネームスペースにあるすべてのメッセージをエクスポートするには次のように指定します。
DO ##class(%Library.MessageDictionary).Export(file)
-
以下のトピックでは、両方のエクスポート方法を簡単に説明します。
1 つの言語での特定ドメインのエクスポート
%Library.MessageDictionaryOpens in a new tab クラス・メソッド ExportDomainList() には以下のシグニチャがあります。
classmethod ExportDomainList(file As %String, domainList As %String, language As %String) returns %Status
引数 | 説明 |
---|---|
file |
(必須) 以下の形式の出力ファイル名のテンプレート : filepath.ext 実際の出力ファイル名は、filepath に language の値が付加され、拡張子 ext が付きます。 |
domainList | (オプション) エクスポートするドメインのコンマ区切りリスト。 |
language | (オプション) 指定した language のみがエクスポートされます。値はすべて小文字の RFC1766Opens in a new tab コードである必要があります。指定しない場合、値は既定でシステムの既定の言語に設定されます。これは、特殊変数 $$$DefaultLanguage に格納されている値です。 |
特定言語のすべてのドメインのエクスポート
%Library.MessageDictionaryOpens in a new tab クラス・メソッド Export() には以下のシグニチャがあります。
classmethod Export(file As %String, languages As %String = "", flag As %String = "") returns %Status
引数 | 説明 |
---|---|
file |
(必須) 以下の形式の出力ファイル名のテンプレート : filepath.ext 出力ファイルの名前は filepathlanguage-code.ext です。 例えば、file が c:/temp/mylang_.txt で、languages に言語コード ja-jp が含まれる場合、出力ファイルの 1 つは c:/temp/mylang_ja-jp.txt という名前になります。 |
languages | (オプション) 言語コードのコンマ区切りリスト。リスト内の各値はすべて小文字の RFC1766Opens in a new tab コードである必要があります。languages が指定されていないか空の場合、データベース内のすべての言語がエクスポートされます。各言語は、file 引数の説明にある規約を使用して別個のファイルにエクスポートされます。 |
flag | (オプション) 指定されている場合、s フラグ (system) は、アプリケーションのメッセージ・ディクショナリ以外にシステムのメッセージ・ディクショナリもエクスポートされることを示します。指定しない場合、アプリケーションのメッセージ・ディクショナリのみがエクスポートされます。 |
メッセージの削除
メッセージを削除するには、以下のコマンドを使用します。
Set status = ##class(%MessageDictionary).Delete(languages,flag)
languages は、オプションの言語コンマ区切りリストです。languages が指定されていない場合、すべての言語が削除されます。既定値では、アプリケーション・メッセージのみが削除されます。s フラグ (system) は、システム・メッセージも削除するかどうかを示すオプションのフラグです。インクルード・ファイルに関連付けられているメッセージ名は常に削除されますが、インクルード・ファイルは削除されません。d フラグ (display) もサポートされます。
メッセージのリスト
指定されたドメインに対してメッセージが読み込まれるすべての言語のリストを取得するには、GetLanguages() メソッドを使用します。
Set list = ##class(%MessageDictionary).GetLanguages(domain,flag)
GetLanguages() は、%ListofDateTypes 形式の言語コードのリストを返します。言語コードは標準の RFC1766Opens in a new tab 形式で、すべて小文字です。domain が指定されている場合、指定されたドメインに対して存在する言語のみがリストに含まれます。指定されていない場合、すべての言語がリストに含まれます。s フラグ (system) は、システム・メッセージまたはアプリケーション・メッセージのどちらでサポートされている言語を返すかを示すオプションのフラグです。既定値では、アプリケーション・メッセージの言語が返されます。d フラグ (display) もサポートされます。