Adobe XDプラグインを多言語対応にするための基本手順
Adobe XDが8つの言語に対応していることをご存知ですか？
この記事を書いている時点で、XDは、英語、フランス語、ドイツ語、日本語、中国語、韓国語、ポルトガル語（ブラジル）、スペイン語をサポートします。これは、世界中の多くのユーザーが、XDを自分の言語で使用していることを意味します。もしプラグイン開発者として、これらのユーザーに最適な体験を提供したければ、国際化とローカライズは、XDプラグイン制作の過程で考慮されるべき事柄でしょう。
コードを書く際は常にそうですが、XDプラグインを複数の言語に対応させる手段はいくつもあります。この記事ではPOJO (Plain Ol’ JavaScript Object) だけを使用する、とても単純なアプローチを紹介します。この方法は、複雑なUIを持たず、いくつかの文字列を翻訳すれば十分なプラグインには最適です。
今後、他の多言語対応の方法もご紹介する予定です。もし、自分自身の手法を共有したいということでしたら、ぜひデベロッパーフォーラムにお知らせください。
サンプルリポジトリ
プラグインの多言語対応に集中できるように、簡易的なリポジトリを設定しておきました。GitHubからコードを入手して、記事を読み進められるようになっています。
リポジトリからプラグインを実行した時、日本語環境であれば、以下のように表示されるでしょう。
そのほかの言語に設定されていれば、以下のように表示されるはずです。
Adobe XD Platformサイトの情報は英語ですが、他のリソースを開いておくのも良い考えかもしれません。
この記事で行う作業
この記事では、XDプラグインを複数言語に対応させるために、以下の作業を行います。
- マニフェストの更新
- UIのテキストを新しいjsonファイルに移動する
- 利用できる言語を確認
- 文字列の読み込み
- 言語に応じたテキストを表示
- フォールバックのためのデフォルトを用意
では、早速始めましょう！
1. マニフェストの更新
コードに手を付ける前に、まずはマニフェストの中身を確認します。
ここでは複数の言語をサポートする際に必要になる項目のみを説明します。マニフェストについての他の情報は、マニフェストのリファレンス（英語）をご覧ください。
注：この記事で使用するマニフェストは新しくなったフォーマットに基づいています。マニフェストの変更情報はこちらの記事をご覧ください。
関連するマニフェストのフィールド
新しく言語を追加するための最初の手順は、以下の2つのフィールドの更新です。
- languages
- label (uiEntryPointsの中)
この例で紹介するプラグインは、英語と日本語をサポートします。そのために、マニフェストには次の2つの作業を行っています。
- languagesフィールドに、サポートする言語それぞれのコードを追加 (“en” と “ja”)
- labelフィールドに、デフォルト言語 (このケースでは英語) と追加の言語 (このケースでは日本語) のテキストをオブジェクトとして設定
以下は、manifestから、関連する箇所の修正後の状態を抜き出したものです。
"languages": ["en", "ja"],
"uiEntryPoints": [
{
"type": "menu",
"label": {
"default": "[Sample] Internationalizing a plugin",
"ja": "[サンプル] プラグインを多言語対応する方法"
},
"commandId": "mainCommand"
}
]
これにより、日本語環境でXDを実行していれば、プラグインメニューには日本語のラベルが表示されるでしょう。さもなければデフォルト言語である英語のラベルを見ることになります。
マニフェストのローカライズに関する今日時点での制限事項
マニフェストのいくつかのフィールドは、現在ローカライズがサポートされていせん。日本語が記述できない主要なフィールドには以下のものがあります。
- Name
- Author
- Summary
- Description
もしこれらが重要であれば (おそらく重要だと思いますので) デベロッパーフォーラムにお知らせください。これらのフィールドも何らかのタイミングでローカライズすることを検討しています。
2. UIのテキストを新しいjsonファイルに移動する
開発者は通常ハードコーディングを避けるものです。しかし、HTMLではそれは容易ではありません。
以下のようなマークアップを記述したとしましょう。
<h1>My website</h1>
… するとハードコードされた文字列が存在することになります。
XDプラグインを国際化するために、これらのハードコードされた文字列をすべてmain.jsのマークアップから取り出して、別のJSONファイルに移動します。このJSONファイルはstrings.jsonという名前にして、main.jsと同じ場所に保存することにします。
ここでは元々のマークアップが以下のようなものだったと想定します。
<h1>Internationalizing your XD plugin</h1>
<p>You can do this with a standard JavaScript object.</p>
<footer>
<button uxp-variant="primary" id="cancel-button">Cancel</button>
<button type="submit" uxp-variant="cta" id="ok-button">OK</button>
</footer>
そして、h1とp、そしてボタンのテキストを取り出して、新しいstrings.jsonファイルに、以下のように言語コード別に分けた形式で配置します。
{
"en": {
"h1": "Internationalizing your XD plugin",
"p": "You can do this with a standard JavaScript object.",
"cancelButton": "Cancel",
"okButton": "OK"
},
"ja": {
"h1": "",
"p": "",
"cancelButton": "",
"okButton": ""
}
}
この後は、日本語のテキストをjaの構造の中に記述するだけです。さらに、新しい言語コードを追加して、他の言語をサポートすることもできます。
次の章は、すでに日本語のローカライズされた文字列が記述されたという前提で話を進めます。 (リポジトリから対応済みのファイルを入手できます)
3. 利用できる言語を確認
プラグインのUIにどの言語の文字列を表示するべきかを知るためには、XD自体のUIが、どの言語で表示されているかを知らなければなりません。
XDプラグインにはそのためのAPIがあります。以下のコードをmain.jsの先頭に追加しましょう。
const { appLanguage } = require("application");
これにより、application.appLanguage属性が、”en” や “ja” などの、XDが現在表示中の言語コードを与えてくれます。
現在、値となりうる候補は以下のとおりです。
- “en” – 英語
- “de” – ドイツ語
- “fr” – フランス語
- “ja” – 日本語
- “ko” – 韓国語
- “zh” – 中国語
- “es” – スペイン語
- “pt” – ポルトガル語
XDの環境の言語が分かったら、マークアップにローカライズされた文字列を表示する下準備は完了です。
4. 文字列の読み込み
ここはごく単純な作業です。main.jsの先頭で、strings.jsonから文字列をインポートしておきましょう。
const strings = require("./strings.json");
このAPIはJSONを自動的にパースします。必要な文字列の変数を、JavaScriptのオブジェクトとして準備してくれるのです。
{
en: {/* strings */},
ja: {/* strings */}
}
では、いよいよすべてをひとつにまとめてみましょう！
5. 言語に応じたテキストを表示
main.jsに記述されているマークアップを、動的に文字列の値を挿入するよう変更します。以下は簡単なサンプルです。
<h1>${strings[appLanguage].h1}</h1>
もしappLanguageが “ja” なら、上のJavaScriptコードは strings[“ja”].h1 になります。より単純に記述するなら、strings.ja.h1 です。
上で見たマークアップにこれを適用します。以下のようなコードになるでしょう。
<h1>${strings[appLanguage].h1}</h1>
<p>${strings[appLanguage].p}</p>
<footer>
<button uxp-variant="primary" id="cancel-button">
${strings[appLanguage].cancelButton}
</button>
<button type="submit" uxp-variant="cta" id="ok-button">
${strings[appLanguage].okButton}
</button>
</footer>
ただし、ここには一つ問題が存在します…
6. フォールバックのためのデフォルトを用意
今の状態では、プラグインがサポートしているのは英語と日本語だけです。もしユーザーがXDをスペイン語環境で実行していたら何が起こるでしょうか？
プラグインは実行されず、デベロッパーコンソールにエラーが表示されることでしょう！
エラーを解釈する
デベロッパーコンソールに表示されるエラーは以下のようなものです。
Plugin TypeError: Cannot read property 'h1' of undefined
この原因は、以下のコードが、strings[“es”].h1 を評価しようとしているためです。
<h1>${strings[appLanguage].h1}</h1>
スペイン語であることを示すため “es” の値がそこにあります。しかし、サンプルはスペイン語をサポートしていません。strings.jsonには該当する言語コードはなく、したがって未定義のエラーが発生することになります。
問題を解決する
プラグインがデフォルト言語にフォールバックできるようにしておきましょう。ここでは以下の2つの作業を行います。
- マニフェストからサポートする言語の配列を取得する
- appLanguageがサポートされる言語に含まれるかを確認し、サポートされない場合はデフォルト言語を指定する
まず最初のステップです。マニフェストのlanguagesをインポートします。
const supportedLanguages = require("./manifest.json").languages;
この例では、supportedLanguagesは [“en”, “ja”] になるでしょう。
次のステップです。appLanguageがsupportedLanguagesに含まれているかをチェックします。
const uiLang = supportedLanguages.includes(appLanguage)
? appLanguage
: supportedLanguages[0];
もしappLanguageが含まれているならそれを使用します。含まれていなければ、サポートする第1言語を選択します。
上のコードでは、マークアップに渡す言語を示すための変数をappLanguageからuiLang変数に置き換えました。ですから、マークアップもそれに合わせて書き換えます。
<h1>${strings[uiLang].h1}</h1>
<p>${strings[uiLang].p}</p>
<footer>
<button uxp-variant="primary" id="cancel-button">
${strings[uiLang].cancelButton}
</button>
<button type="submit" uxp-variant="cta" id="ok-button">
${strings[uiLang].okButton}
</button>
</footer>
プラグインのサンプルは、XDがサポートするすべての言語をサポートしていませんが、今やフォールバックする言語を提供しています。
これで完了です。以上の作業で、英語と日本語をサポートし、英語がデフォルト言語として使われるプラグインができました。
XDプラグインを世界に配布する準備はできていますか？
最初にも話した通り、同じことを実現する手段はいくつもあります。プラグイン次第で、strings.jsonファイルの構造を変更したり、代わりにJavaScriptファイルを用意するかもしれません。localization helperを使ったり、JSフレームワークのモジュール化機能を使う場合もあるでしょう。既にXDプラグインの国際化を行っていて、その経験を共有したい人がいるなら、ぜひ連絡してください！
もし自分のXDプラグインの多言語対応をしたくて、まだそのやり方に不明な点があれば、どんなことでもお聞かせください。
XDプラグインの開発に必要なものを見つけるには、そしてXDプラグインの開発者コミュニティに参加するには、AdobeXDPlatform.comを訪問してみてください。
この記事はHow to Internationalize Your XD Plugin（著者:Ash Ryan Arnwine）の抄訳です