@amazon-devices/keplerscript-kepleri18n-lib

Keplerインターナショナリゼーション（i18n）APIを使用すると、アプリでローカリゼーション機能が有効になります。

注釈

ベストプラクティスとして、UIメッセージは、ソースコードとは別のリソースファイルに保存します。Asset Resolver APIを使用すると、アプリでKeplerの外部文字列リソースを管理できるようになります。Asset Resolver APIでは、リソースファイル形式と、アプリのソースディレクトリ内で想定される文字列リソースファイルの場所の両方が定義されています。アプリはこのAPIを使用して、デバイスのロケールに一致するローカライズされた文字列を取得できるため、ユーザーは自分の使用言語でUIメッセージを表示できます。

開始の手順

セットアップ

package.jsonファイルのdependenciesセクションに、以下のライブラリ依存関係を追加します。

使用方法

以下のセクションでは、Asset ResolverとインターナショナリゼーションAPIの使用方法について説明します。

リソースファイルの定義

最初の手順として、文字列リソースを格納するリソースファイルを作成します。開発者が作成して所有するリソースファイルには、ソース言語のテキストを記述します。文字列リソースのファイル形式はPUFF-Jです。詳細およびPUFF-Jのさまざまなサンプルについては、PUFF-Jのページを参照してください。

留意すべきルールとベストプラクティス：

1. リソースファイルのファイル拡張子は.puff.jsonです。一般的なPUFF-Jリソースファイル名はstrings.puff.jsonです。
2. PUFF-JでリソースIDに使用できる文字セットは、英数字、アンダースコア、ハイフン、コロンに制限されています。このルールは現時点では適用されませんが、近い将来適用される予定です。
3. ベストプラクティスとして、リソースIDには、そのリソースの使用場所と用途を識別できるわかりやすい名前を付けます。たとえば、Wi-Fiセットアップダイアログのタイトルとして使用される文字列リソースには、「wifi-setup-dialog-title」というIDを付けることができます。
4. リソースに関する十分なコンテキストをnote属性に含めます。特にプレースホルダーのある文字列では、プレースホルダーが何を表しているかに関するコンテキストと、プレースホルダーのサンプル値を提供してください。
5. 文字列リソースは複数のPUFF-Jファイルに分けて整理できます。PUFF-Jファイルに定義するリソースキーは、アプリ内のすべてのPUFF-Jファイルセット間で一意でなければならないことに注意してください。複数のPUFF-Jファイルを作成する場合は、リソースキーにアプリ名とファイル名でプレフィックスを付けることを検討してください。これにより、リソースキーの一意性を確保しやすくなります。

PUFF-Jファイルの例：

この例の「Wi-Fi接続に成功しました。ネットワーク：{ssid}」という文字列は、従来のメッセージフォーマットパターンです。実行時に置換されるプレースホルダーを文字列リソースに含める場合、部分的な文字列を連結してメッセージ全体を作成しないようにしてください。コンテキストのない文字列の断片を翻訳して連結すると、メッセージ全体が正しく翻訳されません。Keplerには、メッセージ全体を従来のメッセージフォーマットパターンとして記述できるメッセージフォーマットソリューションが用意されています。これを使用すれば、翻訳者はメッセージ全体を確認して翻訳することができます。MessageFormatClassic APIの使用方法とパターンの指定方法については、メッセージフォーマットに関するガイドを参照してください。

PUFF-Jでは数値リソースもサポートされます。数値リソースは倍精度浮動小数点数型で表されます。

ソースリポジトリ内のリソースファイルの場所

アプリのソース言語のPUFF-Jファイルは、assets/text/サブディレクトリに直接配置します。これらは、ローカリゼーションプロバイダーが翻訳する文字列を取得するソースファイルです。ローカライズされたPUFF-Jファイルは、対応するassets/text/<BCP-47言語タグ>/サブディレクトリに配置します。

BCP-47では、言語と地域のフィールドを区切るサブタグ区切り文字としてハイフンが使用されます（例：en-US）。POSIXプラットフォームのロケールIDとは異なり、アンダースコアは使用されません。

en-US PUFF-Jファイルのシンボリックファイル

ルート／ソース言語のPUFF-Jファイルがアメリカ英語で記述され、en PUFF-Jファイルがイギリス英語で記述されている場合は、en-USサブフォルダを追加し、そのen-USサブフォルダの下に、対応するルートPUFF-Jファイルにリンクするシンボリックリンクを追加します（以下のサブディレクトリツリーの例では、mkdir assets/text/en-US; cd assets/text/en-US; ln -s ../strings.puff.json strings.puff.jsonを実行します）。これにより、en-USロケールで、アメリカ英語のルートPUFF-Jファイルがイギリス英語のen PUFF-Jファイルよりも先に取得されるようになります。

assets/text/サブディレクトリツリーの例：

VPTパッケージツールがアプリパッケージの作成に使用するソースディレクトリに、assetsディレクトリが含まれているかコピーされていることを確認してください。Kepler向けReact Nativeアプリでは、ビルドツールがこれを行います。

リソースファイルに定義されているリソースを取得するAPI

PUFF-Jファイルに定義されているリソースを取得するには、Asset Resolver APIを使用します。

以下の例は、AssetResolverを呼び出す方法を示しています。

文字列リソースのテキスト基準方向が、テキストUIウィジェットのデフォルトのテキスト基準方向と異なる可能性がある場合は、文字列リソースのdir属性をテキストUIウィジェットに設定します。たとえば、英語のUIにアラビア語の文字列リソースを表示する場合は、テキストUIウィジェットのテキスト基準方向属性を、アラビア語のPUFF-Jリソースファイルに設定されているdir属性値であるrtl（右から左）に設定します。

選択分岐および複数形分岐文字列リソースタイプの場合、AssetResolver.getString()はリソースを従来のメッセージフォーマットパターン文字列として返します。リソースタイプの詳細については、「PUFF-Jファイル形式」トピックのリソースタイプを参照してください。

返されたパターン文字列とMessageFormatClassicクラスを使用して、フォーマットされた文字列を生成する方法については、メッセージフォーマットに関するガイドを参照してください。

文字列フォーマット

メッセージフォーマット

ユーザーに表示するメッセージには、実行時に設定される名前、数値、日付、時刻などの変数を含めることができます。ローカライズされたメッセージの翻訳文では、ターゲット言語の文法に基づいて語順が変わることがよくあります。このため、翻訳者は、メッセージの翻訳文中で変数を移動できる必要があります。これが可能になるのは、変数のプレースホルダーを含むメッセージ全体が翻訳者に提供された場合だけです。断片的なフレーズをソース言語の文法に基づいて連結していると、メッセージが翻訳不可能になる可能性があります。Keplerは、メッセージ内に変数のプレースホルダーを挿入できるメッセージフォーマットソリューションを提供しています。このメッセージフォーマットパターンを使用すると、開発者はメッセージ全体をローカライズしやすい形で記述できます。

MessageFormatClassicクラスには、従来のICU MessageFormatパターンが採用されています。パターンのチュートリアルとリファレンスについては、従来のICU MessageFormatのガイド（英語のみ）を参照してください。従来のICU MessageFormatパターンが最初に登場したときから、ベストプラクティスにいくつかの変更点があります。その中で最も重要なのが、番号／位置で指定する引数ではなく、名前付き引数の使用への転換です。名前付き引数の例を参考にしてください。また、MessageFormatClassicクラスは、そのコード例に示されている方法ではなく、パターンと共に使用してください。

注： Unicodeには、新しいメッセージフォーマット標準のドラフトを作成するワーキンググループ（英語のみ）があります。標準がリリースされたら、Keplerに組み込むかどうかを検討する予定です。

MessageFormatClassicでは、パターン内のプレースホルダーの形式として、名前付き引数と番号の引数の両方がサポートされます。推奨されるのは名前付き引数の形式です。わかりやすい名前のプレースホルダーを使用すれば、開発者と翻訳者の両方にとって読みやすさが向上し、パターン内のプレースホルダーにどのような値が入るかをより正確に推測できるためです。

Kepler向けReact Nativeのメッセージフォーマットの使用方法

以下の手順は、MessageFormatClassicクラスの使用方法を示しています。

1. @amazon-devices/keplerscript-kepleri18n-libパッケージからMessageFormatClassicをインポートします。

   コードをコピー クリップボードにコピーしました。

    import { MessageFormatClassic } from '@amazon-devices/keplerscript-kepleri18n-lib';
   

2. MessageFormatClassicクラスで名前付き引数スタイルのパターンを使用するには、JavaScriptの組み込みのMapオブジェクトを作成し、引数名とそれに対応する値のマッピングを設定します。次に、設定したMapインスタンスをパターンと共にMessageFormatClassic.format()メソッドに渡します。

   以下の例に示すように、番号引数スタイルのパターンではなく名前付き引数スタイルのパターンを使用します。

   コードをコピー クリップボードにコピーしました。

    import { MessageFormatClassic } from '@amazon-devices/keplerscript-kepleri18n-lib';
    ...
        // パターンは文字列リソースから取得してください。ここでは例を簡単にするためにハードコードしています。
        const pattern: string = "カーナンバー{carNumber}の勝ち！ おめでとう、{driverName}！";
        const carNumber: number = 3;
        const driverName: string = "アリス";
        const argMap = new Map<string, number | string | Date>();
        argMap.set("carNumber", carNumber);
        argMap.set("driverName", driverName);
        const message: string | null = MessageFormatClassic.format(pattern, argMap);
        if (message === null) {
            // エラー
            return;
        }
        // メッセージは「カーナンバー3の勝ち！ おめでとう、アリス！」
   

3. MessageFormatClassicクラスで番号引数スタイルのパターンを使用するには、パターンと引数の値を指定してMessageFormatClassic.formatPositional()メソッドを呼び出します。このとき、引数の値は番号引数と同じ順番で渡します。たとえば、パターンパラメーターの後、引数0（{0}）の値を最初に指定します。パターンに複数の引数がある場合は、続けて引数1（{1}）の値を指定し、以下同様になります。

   以下の例は、番号引数スタイルのパターンの使用方法を示しています。

   コードをコピー クリップボードにコピーしました。

    import { MessageFormatClassic } from '@amazon-devices/keplerscript-kepleri18n-lib';
    ...
        // パターンは文字列リソースから取得してください。ここでは例を簡単にするためにハードコードしています。
        const pattern: string = "カーナンバー{0}の勝ち！ おめでとう、{1}！";
        const carNumber: number = 11;
        const driverName: string = "ボブ";
        const message: string | null = MessageFormatClassic.formatPositional(pattern, carNumber, driverName);
        if (message === null) {
            // エラー
            return;
        }
        // メッセージは「カーナンバー11の勝ち！ おめでとう、ボブ！」
   

測定単位

温度、距離、速度、電力、トルク、圧力などの測定単位をフォーマットするには、前述のメッセージフォーマットを使用して、パターン内に計測単位スケルトンを含めます。

• 従来のICU MessageFormatパターンでのスケルトンの指定（英語のみ）
• 数値スケルトン（英語のみ。測定単位のフォーマットのサポートが含まれています）
• Unicode CLDRによる使用可能な測定単位（英語のみ）

以下は、測定単位スケルトンを含む従来のICU MessageFormatパターンの例です。

経過時間／期間

Kepler向けReact Nativeでは、ECMAScript Intl.DurationFormatオブジェクト（ステージ3提案）を利用できます。APIドキュメントとサンプルはMozilla MDN Web Docsで公開されています。TC39のAPI提案はGitHub（英語のみ）にあります。

アルファベット順および自然順でのソート／照合

Kepler向けReact Nativeでは、ECMAScript Intl.Collatorオブジェクトを利用できます。APIドキュメントとサンプルはMozilla MDN Web Docsで公開されています。

アプリ／システムのロケールとタイムゾーンの設定

I18nManagerには、アプリのロケールとタイムゾーンの設定の変更を取得、変更、リッスンする関数が用意されています。APIの詳細については、Kepler向けReact NativeのインターナショナリゼーションとローカリゼーションAPIのI18nManagerセクションを参照してください。

モジュール

• MessageFormatClassic
• ProductNameFormat

---

Last updated: 2025年9月29日