©2009 Google - Code サイト ホーム - 利用規約 - プライバシー ポリシー - サイト ディレクトリ
Google Code が利用できる言語: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
| 
日本語 | ログイン
このドキュメントでは、各国の言語に簡単にローカライズできるガジェットの作成方法について説明します。
Gadgets API を使用すると、さまざまな言語に簡単にローカライズできるガジェットを作成できます。その仕組みは単純です。ガジェットを構造化することにより、ユーザーに表示されるテキスト (つまり、翻訳が必要なすべてのテキスト) をメッセージ バンドルにまとめ、ガジェットとは別に管理します。これらのストリングを別途翻訳したら、ロケールごとのメッセージ バンドルを作成し、それらをガジェットのスペックに追加します。これで、ガジェットのユーザーが他の国にも広がります。
英語以外のガジェットの詳細については、英語以外の言語によるガジェットをご覧ください。
このドキュメントでは、国際化とローカライズについて説明します。
このドキュメントでは、ユーザーのドメインに基づく「国」と、ユーザー インターフェイスとして設定されている「言語」の 2 つを、ユーザーの「ローカライズ プロファイル」と呼びます (詳細については、テストをご覧ください)。
Gadgets API では、XML 属性値や <Content> セクションにおいて UTF-8 エンコーディングがサポートされます。コンテンツ タイプが html に設定されている場合、UTF-8 がデフォルトのエンコーディングに明示的に設定されます。手動で設定を行わないようにしてください。
このドキュメントでは、「Hello World」というメッセージを表示するサンプル ガジェットを使用します。下の図では、メッセージが中国語で表示されています。
このサンプルでは、ユーザーがドロップダウン メニューを使用して、「Hello World」メッセージのフォントの色を指定できます。メニューに表示される色名は、外部ファイル (メッセージ バンドル) で定義します。メニューがどの言語で表示されるかは、ユーザーの言語/国プロファイルによって決まります。英語プロファイルのユーザーがこのガジェットを実行すると、テキストが英語で表示されます。下に示すように、英語バージョンのサンプルでは、ユーザー設定ドロップダウン メニューが英語で表示されます。
Hello World ガジェットのスペックについてはこちらをご覧ください。
ガジェットをローカライズする基本的な手順は次のとおりです。
ガジェットの国際化で中心的な役割を果たすのがメッセージ バンドルです。メッセージ バンドルとは、特定のロケール用に翻訳されたストリングを含む XML ファイルです。各ストリングは、バンドル間で共通の一意の名前で識別されます。
メッセージ バンドルは、どのような URL でもホストでき、アプリケーション間で共有することも可能です。メッセージ バンドルに格納されるロケールは 1 つのみです。
次に、メッセージ バンドルのフォーマットを示します。
<messagebundle>
<msg name="hello_world">
Hello World.
</msg>
<msg name="color">Color</msg>
<msg name="red">Red</msg>
<msg name="green">Green</msg>
<msg name="blue">Blue</msg>
<msg name="gray">Gray</msg>
<msg name="purple">Purple</msg>
<msg name="black">Black</msg>
</messagebundle>
メッセージ バンドル ファイルには、以下のフィールドを含めることができます。
メッセージ バンドルは、慣例に従って次のように命名します。
<language>_<country>.xml
言語や国を指定しない場合は「ALL」を使用します。たとえば、de_ALL.xml というファイルは、国に関係なく、ドイツ語を使用するすべての人に適用されます。ALL_ALL.xml メッセージ バンドルは、デフォルトで使用されるファイルです。
メッセージ バンドルの命名には、必ず従わなければならない要件はありません。ガジェットでは、<Locale> の lang および country 属性によって、ユーザーのプロファイルに合った適切なメッセージ バンドル ファイルが特定されます。メッセージ バンドル自体の名前で識別されるわけではありません。
ただし、いくらGadgets API に柔軟性があるといっても、以下のガイドラインには従うことをお勧めします。
<ModulePrefs> セクションで <Locale> タグをネストさせることにより、そのガジェットで使用するメッセージ バンドルのリストを記述できます。次に例を示します。
<ModulePrefs title="i18n Example"> <Locale messages="http://doc.examples.googlepages.com/ALL_ALL.xml"/> <Locale lang="de" messages="http://doc.examples.googlepages.com/de_ALL.xml"/> <Locale lang="zh-cn" messages="http://doc.examples.googlepages.com/zh_cn_ALL.xml"/> <Locale lang="fr" messages="http://doc.examples.googlepages.com/fr_ALL.xml"/> <Locale lang="ja" messages="http://doc.examples.googlepages.com/ja_ALL.xml"/> <Locale lang="es" messages="http://doc.examples.googlepages.com/es_ALL.xml"/> <Locale lang="it" messages="http://doc.examples.googlepages.com/it_ALL.xml"/> <Locale lang="ru" messages="http://doc.examples.googlepages.com/ru_ALL.xml"/> </ModulePrefs>
<Locale> には、以下の属性を指定できます。
messages: URL でアクセスするメッセージ バンドル。 lang: メッセージ バンドル ストリングの翻訳後の言語。 country: 国属性 (サンプルの「Hello World」ガジェットのスペックでは使用されていません)。たとえば、次のメッセージ バンドルは、フランス語を使用するカナダ人ユーザー用です。 <Locale lang="fr" country="CA" messages="http://example.com/fr_CA.xml"/>
実行時のガジェットでは、ユーザーのプロファイルに最も近いメッセージ バンドルが選択されます。
言語の有効な値は、ISO639-1 の 2 桁の言語コードです。国には ISO 3166-1 alpha-2 コードが使用されます。
メッセージ バンドルは、フォールバック機能を備えています。このメッセージ フォールバック機能により、ユーザーの国および言語の UI 設定 (URL で指定) に最も近いメッセージ バンドルを使用してガジェットが実行されます。つまり、完全に一致するメッセージ バンドルが見つからない場合でも、使用可能なメッセージ バンドルを順番に「フォールバック」 (代替) することで、最も近いメッセージ バンドルを検出します。
メッセージ フォールバックを使用することで、特定のロケールに合うメッセージ バンドルが見つからなかった場合に表示する「デフォルト」のメッセージ (通常は ALL_ALL.xml 内に記述) を設定することもできます。
たとえば、ガジェットで以下のように指定したとします。
<Locale messages="http://x.com/ALL_ALL.xml"/> <Locale lang="de" messages="http://x.com/de_ALL.xml"/> <Locale lang="de" country="DE" messages="http://x.com/de_DE.xml"/> <Locale lang="de" country="US" messages="http://x.com/de_US.xml"/>
これらのファイルは、どのような優先順位で使用されるでしょうか。まずは、ユーザーのドメインが US (http://www.google.com) で、言語がドイツ語の場合を考えてみましょう。このユーザーに対しては、de_US.xml ファイルのメッセージが表示されます。このファイルに特定のメッセージが含まれていない場合は、de_ALL.xml のメッセージが表示され、このファイルにも見つからない場合は最終的に ALL_ALL.xml のメッセージが表示されます。
一方、ドイツ在住のドイツ語 UI ユーザーに対しては de_DE.xml、スイス在住のドイツ語 UI ユーザーに対しては de_ALL.xml、スイス在住のフランス語 UI ユーザーに対しては ALL_ALL.xml のメッセージが最初に表示されます。
ガジェットでは、メッセージ バンドル内の適切なメッセージを、どのようにして特定しているのでしょうか。「Hello World」サンプルの de_ALL.xml (言語がドイツ語で国が ALL) の場合で考えてみましょう。
<messagebundle>
<msg name="hello_world">
Hallo Welt.
</msg>
<msg name="color">Farbe</msg>
<msg name="red">Rot</msg>
<msg name="green">Grün</msg>
<msg name="blue">Blau</msg>
<msg name="gray">Grau</msg>
<msg name="purple">Purpurrot</msg>
<msg name="black">Schwarz</msg>
</messagebundle>
各メッセージには、それぞれを識別するための一意な名前ストリングが割り当てられています。次にメッセージの例を示します。
<msg name="red">Rot</msg>
このメッセージの一意なメッセージ名は「red」で、ガジェット (この場合はユーザー設定ドロップダウン メニュー) に表示される翻訳済みストリングは、ドイツ語で赤を意味する「Rot」です。これに相当する英語メッセージ ストリングは、次に示すようにメッセージ バンドル ALL_ALL.xml に含まれています。
<msg name="red">Red</msg>
「Hello World」ガジェットのスペックでは、適切なメッセージ バンドルから取得した値をどこに代入するかを、__MSG_ 代入変数を使用して特定します。たとえば、「Hello World」ガジェットのスペックに含まれている次の XML 文では、ユーザー設定の「Color」ドロップダウン メニューにメニュー項目を追加しています。
<EnumValue value="Red" display_value="__MSG_red__" />
この行は、「ユーザーの国/言語プロファイルに最も近いメッセージ バンドルを探し、「red」という名前のメッセージを取得して __MSG_red__ に代入する」という意味です。「Hello World」サンプルでは、このような方法で、ユーザー設定ドロップダウン メニューに色名 (ここではドイツ語の色名) を設定しています。
ガジェットの XML 部分にメッセージを表示する場合も、上で説明した代入変数を使用します。ガジェットの CDATA 部分には、これとは異なるいくつかの方法でメッセージを表示できます。
一番単純なのは、次のように代入変数を HTML に埋め込む方法です。
<b>__MSG_hello_world__</b>.
また、ユーザー設定関数 getMsg() を使用する方法もあります。この関数は、ユーザー設定関数と呼ばれていますが、ユーザー設定に関するメッセージだけでなく、メッセージ バンドル内のすべてのメッセージに使用できます。ただし、この関数は Prefs オブジェクト上で呼び出す必要があります。次に例を示します。
var prefs = new gadgets.Prefs(); prefs.getMsg(“red”);
次に、Hello World サンプル ガジェットのスペックを示します。
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="i18n Example">
<Locale messages="http://doc.examples.googlepages.com/ALL_ALL.xml"/>
<Locale lang="de" messages="http://doc.examples.googlepages.com/de_ALL.xml"/>
<Locale lang="zh-cn" messages="http://doc.examples.googlepages.com/zh_cn_ALL.xml"/>
<Locale lang="fr" messages="http://doc.examples.googlepages.com/fr_ALL.xml"/>
<Locale lang="ja" messages="http://doc.examples.googlepages.com/ja_ALL.xml"/>
<Locale lang="es" messages="http://doc.examples.googlepages.com/es_ALL.xml"/>
<Locale lang="it" messages="http://doc.examples.googlepages.com/it_ALL.xml"/>
<Locale lang="ru" messages="http://doc.examples.googlepages.com/ru_ALL.xml"/>
</ModulePrefs>
<UserPref name="fontcolor" display_name="__MSG_color__" default_value="Red" datatype="enum">
<EnumValue value="Red" display_value="__MSG_red__" />
<EnumValue value="Green" display_value="__MSG_green__" />
<EnumValue value="Blue" display_value="__MSG_blue__" />
<EnumValue value="Gray" display_value="__MSG_gray__" />
<EnumValue value="Purple" display_value="__MSG_purple__" />
<EnumValue value="Black" display_value="__MSG_black__" />
</UserPref>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
// Display message in the user's preferred language
function displayMsg(){
var div = document.getElementById('content_div');
// Get userprefs
var prefs = new gadgets.Prefs();
// Set font color to user's color choice
div.style.color = prefs.getString("fontcolor");
// Display message
var html = "<br><h1>";
// Use prefs.getMsg to go to the appropriate message bundle
// and get the string associated with the "hello_world" message.
html += prefs.getMsg("hello_world");
html += "</h1>";
div.innerHTML = html;
}
gadgets.util.registerOnLoadHandler(displayMsg);
</script>
]]>
</Content>
</Module>
Gadgets BIDI (双方向性) API を使用すると、ガジェットの方向を動的に変更できます。ここでいう「方向」とは、コンテンツの表示方向 (左から右に表示するか、右から左に表示するか) です。位置合わせのことではありませんので注意してください。たとえば、ガジェットに英語のテキストを表示する場合、右揃えにすることはできますが、テキスト自体は左から右の方向に表示する必要があります。
BIDI API を使用すると、英語のように左から右に表示する言語だけでなく、ヘブライ語やアラビア語のように右から左に表示する言語にも対応したガジェットを記述できます。BIDI API には以下が含まれています。
<Locale...> タグの language_direction 属性。値には、「rtl (右から左)」または「ltr (左から右)」のいずれかを使用できます。この属性を使用して、ガジェットの方向を設定します。デフォルトの方向は左から右です。 __BIDI_... 代入変数のセット。これらの変数の値は、ガジェットの方向に応じて変化します。たとえば、変数 __BIDI_DIR__ の値は、ガジェットの方向が左から右の場合は「ltr」になり、右から左の場合は「rtl」になります。 もちろん、<Locale... language_direction="rtl"> のように、ガジェットの方向を静的に設定することもできます。たとえば、ヘブライ語のテキストしか表示しないガジェットであれば、次のようにテキストが常に右から左に表示されるように設定できます。
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="כותרת two-כיוונית"
height="100">
<Locale lang="ALL" language_direction="rtl" />
</ModulePrefs>
<Content type="html"><![CDATA[
אני כותב מימין לשמאל ולא הייתי צריך להגדיר
dir=rtl בשביל זה!<br>
]]>
</Content>
</Module>
次に、ガジェットに含まれている メッセージ バンドルに、左から右に表示すべきものと、右から左に表示すべきものがある場合を考えてみましょう。両方向の表示をサポートするガジェットは、どのように設計したらよいでしょうか。次に示すのは、ユーザーのロケールに応じて読み込まれたメッセージ バンドルによって、動的に表示方向が変化するガジェットの例です。このガジェットには、右から左に表示する言語として、ヘブライ語 (iw) とアラビア語 (ar) の 2 つのメッセージ バンドルが含まれています。
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="BIDI Hello World"> <Locale messages="http://doc.examples.googlepages.com/ALL_ALL.xml"/> <Locale lang="ru" messages="http://doc.examples.googlepages.com/ru_ALL.xml"/> <Locale lang="fr" messages="http://doc.examples.googlepages.com/fr_ALL.xml"/> <Locale lang="ja" messages="http://doc.examples.googlepages.com/ja_ALL.xml"/> <Locale lang="es" messages="http://doc.examples.googlepages.com/es_ALL.xml"/> <Locale lang="it" messages="http://doc.examples.googlepages.com/it_ALL.xml"/> <Locale lang="iw" messages="http://doc.examples.googlepages.com/iw_ALL.xml" language_direction="rtl"/> <Locale lang="ar" messages="http://doc.examples.googlepages.com/ar_ALL.xml" language_direction="rtl"/> </ModulePrefs> <Content type="html"> <![CDATA[ <div style="margin-__BIDI_START_EDGE__:30px;"><h2>__MSG_hello_world__</h2></div> ]]> </Content> </Module>
ここで、ユーザーの言語設定がアラビア語になっているとします。<Locale
lang="ar" messages="http://.../ar_ALL.xml" language_direction="rtl"/> という行は、「アラビア語の場合は、メッセージ バンドル ar_ALL.xml のテキストを表示し、ガジェットの方向を rtl に設定する」という意味です。ヘブライ語の場合も、方向は右から左に設定されます。それ以外の言語の場合、ガジェットの方向はデフォルトの ltr (左から右) に設定されます。
<div style="margin-__BIDI_START_EDGE__:30px;"><h2>__MSG_hello_world__</h2></div> という行は、「ガジェットの方向が左から右の場合はテキストを左端から 30 ピクセル分オフセットし、ガジェットの方向が右から左の場合はテキストを右端から 30 ピクセル分オフセットする」という意味です。たとえば、ユーザーのブラウザ設定がアラビア語 (右から左) の場合、実行時には次のように代入されます。
<div style="margin-right:30px;"><h2>أهلاً بالعالم</h2></div>
次の表に、BIDI 代入変数と、それぞれが取ることのできる値を示します。なお、これらの値は、常にガジェット自体の方向との相対値になります。つまり、BIDI 代入変数は、常に <Locale... language_direction="..."> 設定と組み合わせて使用するということです。これらの変数は、ガジェットのボディ内であればどこででも使用できます。
| 変数 | 説明 |
|---|---|
__BIDI_START_EDGE__ |
この変数は、コンテンツ表示の開始点を、ガジェットのどちら側にするかを表します。値は、ガジェットが LTR モードの場合は「left」、ガジェットが RTL モードの場合は「right」になります。上に示したガジェットでは、CSS のマージン設定でこの変数を使用しています。 |
__BIDI_END_EDGE__ |
この変数は、コンテンツ表示の開始点の逆側を表します。値は、ガジェットが LTR モードの場合は「right」、ガジェットが RTL モードの場合は「left」になります。 |
__BIDI_DIR__ |
この変数の値は、ガジェットが LTR モードの場合は「ltr」、ガジェットが RTL モードの場合は「rtl」になります。 |
__BIDI_REVERSE_DIR__ |
この変数の値は、ガジェットが LTR モードの場合は「rtl」、ガジェットが RTL モードの場合は「ltr」になります。 |
BIDI API では、ガジェット全体の方向を変更したり、ガジェットのコンテンツに応じて方向を変更したりできます。しかし、ガジェット内のテキスト行ごとに方向を調整したい場合もあるかもしれません。ユーザーの言語設定や特定の言語にしばられることなく、行ごとに方向を変えるような場合です。たとえば、英語とヘブライ語を同時に表示するガジェットが考えられます。さまざまな言語のフレーズを一覧で紹介するガジェットもこれに当てはまるでしょう。このような場合は、通常の DOM 関数呼び出しと CSS を使用して、ガジェット ボディ内のテキストの表示方向を設定できます。次に例を示します。
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="DOM Hello World" height="200" />
<Content type="html"><![CDATA[
<script type="text/javascript">
// In this gadget, users choose a language from a drop-down menu, and the gadget displays
// a "Hello World" message for the selected language. The gadget uses DOM functions to set
// the direction and formatting for the message, depending on whether its language is RTL
// or LTR.
// Associative array containing "Hello World" messages for different languages
var msgs = new Object();
msgs = {
"English" : "Hello World",
"Hebrew" : "שלום עולם",
"French" : "Bonjour Monde",
"Arabic" : "أهلاً بالعالم",
"Russian" : "Здравствуйте Мир!"
};
function showMsg() {
var html="<h1>";
var div = _gel('mydiv');
div.style.color = "green";
var index = document.myform.Language.selectedIndex;
var lang = document.myform.Language.options[index].text;
var str = msgs[lang];
if (!str)
str="";
// If language is Hebrew or Arabic, set the div direction to be right-to-left.
// Offset text 30px from right margin.
if(lang=="Hebrew" || lang=="Arabic") {
div.style.direction = "rtl";
div.style.marginRight = "30px";
html += str;
}
// For other languages, set div direction to left-to-right.
// Offset text 30px from left margin.
else {
div.style.direction = "ltr";
div.style.marginLeft = "30px";
html += str;
}
html+= "</h1>";
div.innerHTML = html;
}
</script>
<div style="background-color: #BFCFFF; height: 200px; color:green;">
<br />
<div>
<form name="myform" style="text-align: center;">
<select name="Language" onchange="showMsg()">
<option>Pick a Language
<option>English
<option>Hebrew
<option>French
<option>Arabic
<option>Russian
</select>
</form>
</div>
<br />
<div id="mydiv"><h2 style='text-align: center;'>****Pick a language****</h2></div>
</div>
]]>
</Content>
</Module>
ガジェットをテストするには、それに含まれているメッセージ バンドルに合わせて、国および言語の設定を変更します。
iGoogle 内での国および言語の設定は、URL で変更するのが最も簡単な方法です。
http://www.google.com/ig?&gl=<country>&hl=<lang>
たとえば次の URL では、国をドイツ (DE)、言語を英語 (en) に設定しています。通常、言語設定よりも国設定が優先されるため、この URL の場合はテキストがドイツ語で表示されます。
http://www.google.com/ig?&gl=DE&hl=en
次の例では、国は暗黙的に US、言語はスペイン語に設定されています。
http://www.google.com/ig?hl=es
各言語を正しく指定した URL を作成する方法については、http://www.google.com/help/customize.html#searchlang をご覧ください。言語の有効な値は、ISO639-1 の 2 桁の言語コードです。国には ISO 3166-1 alpha-2 コードが使用されます。
メッセージ バンドルのキャッシング動作は、ガジェットのスペックに定義されている動作と同じです。通常は、1 ～ 2 時間ごとにキャッシュが更新され、ホスティング サーバーで受け付けるリクエストもせいぜい 1 日 100 ～ 200 程度です。サーバーを利用できない場合は、以前取得したコピーを可能な限り使用し続けます。developer.xml ガジェットでは、ガジェットのキャッシュを無効にすると、ガジェットのメッセージ バンドルのキャッシングも無効になります。
ガジェットの開発時には、メッセージが表示されるべき場所が空白になる場合や、??? と表示される場合があります。原因としては以下が考えられます。