APLテンプレートを効率的にローカライズする

Note: Sign in to the developer console to build or publish your skill.

スキルとそのAPLドキュメントでは通常、独自の言語、習慣、文化的慣習、規制を持つさまざまな地域に居住するAlexaユーザー向けに、マルチモーダルな音声エクスペリエンスが提供されます。

画面に表示される情報の翻訳は、APLプロジェクトのローカライゼーションにおいて、考慮すべき多くの要素の1つにすぎません。以下は、テンプレートを効率的にローカライズするために考慮すべき事項の一部です。

表示テキストは、ユーザーが話す各言語に翻訳する必要があります。
画像、オーディオファイル、ビデオなどのメディアアセットでは、音声テキストや表示テキストがソースにエンコードされていることがあります。そのため、場合によっては、これらのメディアファイルのローカライズされたバリエーションを作成する必要があります。APLのローカライゼーションでは、各ファイルに対応するローカライズされたURL文字列の指定が課題となることがよくあります。
レイアウトの方向は、ユーザーのデバイスの言語設定に応じて、「左から右」または「右から左」のいずれかになります。レイアウトの方向によって、コンポーネントの配置の変更だけでなく、視覚コンポーネントの再配置、並べ替え、サイズ変更が必要になる場合もあります。
数値、日付、時刻、単位の形式は、ユーザーのロケールによって異なります。
場合によっては、APLテンプレートで視覚的要素を追加・削除したり、コンポーネントの機能や表示動作を変更したりすることで、特定の文化的嗜好、慣習、規制に適応することもできます。

ローカライゼーションを実現する最も簡単な方法は、ロケールと言語ごとに専用のAPLテンプレートを用意することです。ただし、この方法では冗長で一貫性のないテンプレートコードが大量に生成されるため、APLプロジェクトのアーティファクトの保守効率が低下します。

一般的に、APLテンプレートのローカライゼーションは、ローカライズの対象となる部分を抽出して、すべてのロケールでグローバルに共通するコンテンツや機能から分離することで最適化できます。APLプロジェクトを新しいロケールに拡大する予定がすぐにはない場合でも、最初からローカライゼーションをサポートするようにテンプレートをデザインすることをお勧めします。ただし、テキストなどのローカライズされたコンテンツをAPLテンプレートにハードコーディングすることは避けてください。

APLリソースをローカライズする

APLテンプレートをローカライズする際の最も一般的なタスクは、翻訳済みのテキスト文字列をテンプレートで指定し、ユーザーの言語で情報を表示できるようにすることです。これは、以下の方法で行うことができます。

翻訳済み文字列をAPLテンプレートにハードコードする

これは、APLテンプレートをローカライズするうえで最も好ましくない方法です。この方法では、テンプレート全体を複製して、ユーザーのロケールごとに新しいバージョンを提供する必要があるためです。

翻訳済み文字列をデータソースで指定する

APLテンプレートのデータソースを通じて、スキルで翻訳済み文字列を指定します。これは、文字列に動的コンテンツが含まれている場合や、文字列がデータソースの一部としてデータエンティティにリンクされている場合に有効です。たとえば、ローカライズされた商品タイトルと説明を含む商品リストがデータソース内に含まれている場合などが挙げられます。ただし、スキル応答にはバイトサイズの制限があるため、翻訳済み文字列（特に、長いテキスト文字列）をデータソースの一部として含めるには限界があります。

以下は、ローカライズされたテキスト文字列をデータソース内に含むRenderDocumentディレクティブをスキルから返す方法の例です。

return {
    type: 'Alexa.Presentation.APL.RenderDocument',
    token: 'myToken',
    document: {
        type: 'APL',
        version: '2022.1',
        mainTemplate: {
            parameters: [ "localizedStrings" ],
            items: [
                {
                    type: "Text",
                    text: "${localizedStrings.welcome}"
                }
            ]
        }
    },
    datasources: {
        localizedStrings: {
            welcome: 'APLへようこそ'
        }
    }
}

翻訳済み文字列をAPLリソース文字列として指定する

Alexaスキルから返されるAPLドキュメントで、翻訳済み文字列をAPLリソース文字列として指定します。詳細については、APLリソースを参照してください。このアプローチでは、ローカライズされた文字列がスキルによってRenderDocumentディレクティブの応答に「ハードコード」されるため、技術的にはローカライズされた文字列をデータソースに配置する手法と似ています。このアプローチを採用する主な理由は、静的な情報を動的な情報に置き換える場合など、インポートされたAPLパッケージに既に存在する特定のリソース文字列を上書きできる点です。

以下の場合は、APLドキュメント内に文字列リソースを含むRenderDocumentディレクティブがスキルから返されます。

return {
    type: 'Alexa.Presentation.APL.RenderDocument',
    token: 'myToken',
    document: {
        type: 'APL',
        version: '2022.1',
        resources: [
            {
                strings: {
                    welcome: "APLへようこそ"
                }
            }
        ],
        mainTemplate: {
            items: [
                {
                    type: "Text",
                    text: "${@welcome}"
                }
            ]
        }
    }
}

翻訳済み文字列をAPLリソースパッケージで指定する

APLドキュメントにインポートされるAPLパッケージで、翻訳済み文字列をAPLリソース文字列として指定します。詳細については、APLリソースとAPLパッケージを参照してください。これは、APLドキュメントにグローバルに静的文字列を提供するためのベストプラクティスですが、ローカライゼーションの効果的な戦略とするには、解決すべき大きな課題が1つあります。APLパッケージからローカライズされたリソースをインポートする場合、パッケージが特定のロケール専用でない限り、パッケージには言語ごとに翻訳された文字列リソースが含まれている必要があります。条件付きリソースブロック式内でlang環境変数を使用すると、現在のユーザーロケールに応じて文字列値を解決できます。APLリソースパッケージは、以下のコード例のようになります。

{
  "type": "APL",
  "version": "2022.1",
  "resources": [
    {
      "strings": {
        "welcome": "ようこそ"
      }
    },
    {
      "when": "${environment.lang == 'en-US'}",
      "strings": {
        "welcome": "Welcome"
      }
    },
    {
      "when": "${environment.lang == 'es-ES'}",
      "strings": {
        "welcome": "Bienvenido"
      }
    }
  ]
}

翻訳済み文字列をロケール固有のAPLリソースパッケージで指定する

特定のロケール専用のAPLパッケージで、翻訳済み文字列をAPLリソース文字列として指定します。このアプローチにより、すべてのロケールの翻訳済み文字列を1つのAPLパッケージに含め、現在のユーザーロケールに基づいて動的に選択する場合の問題が解決されます。代わりに、スキルはユーザーからの呼び出し時に認識される現在のロケールに応じて、ローカライズされたAPLパッケージのインポートパスをRenderDocumentディレクティブの応答にハードコードします。APLテンプレートではこのプロパティに動的な式を使用できないため、インポートのソースURLの作成はスキルコード側でのみ行うことができます。

return {
    type: 'Alexa.Presentation.APL.RenderDocument',
    token: 'myToken',
    document: {
        type: 'APL',
        version: '2022.1',
        import: [
            {
                name: "my-local-strings",
                source: 'https://path.to/my/local-strings-for-' + locale + '.json',
                version: '1.0'
            }
        ],
        mainTemplate: {
            items: [
                {
                    type: "Text",
                    text: "${@welcome}"
                }
            ]
        }
    }
}

リソース文字列には、表示テキストだけでなく、ローカライズの対象となる画像やビデオなどのメディアアセットのURLも含まれます。さらに、APLリソースでは文字列だけでなく、色、ディメンション、数値、ブール値など、動的なAPLコンポーネントを追加するために使用できるその他のリソースタイプもサポートされます。これらのコンポーネントの外観や機能的動作は、ローカライズされたリソース値に依存します。たとえば、APL Imageの表示やAPL Frameの背景色は、ローカライズされたリソース変数に基づいてAPLテンプレートで動的に設定できます。

スタイルをローカライズする

場合により、ユーザーロケールに応じてレイアウトやスタイルをカスタマイズする必要があります。最も一般的な例は、レイアウト方向です。これは既にAPLドキュメントの設定として扱われており、グローバルに簡単に設定できます。ただし、APLコンポーネントの位置やサイズの変更、並べ替え、その他の外観のカスタマイズなど、より具体的なニーズが生じる場合もあります。

簡単なアプローチとしては、APLコンポーネントを複製し、そのwhenプロパティを使用して、特定のユーザーロケール専用のコンポーネントのみをインフレートしてレンダリングする方法があります。ただし、これはテンプレートデザインとしては効率的でない場合があるため、注意が必要です。

{
    "type": "Text",
    "when": "${environment.lang == 'ja-JP'}",
    "color": "green",
    "text": "${@welcome}"
 },
 {
    "type": "Text",
    "when": "${environment.lang != 'ja-JP'}",
    "color": "red",
    "text": "${@welcome}"
}

代わりに、ローカライズされたAPLリソース（ディメンション、ブール値、色、イージング関数など）を使用して、個々のAPLコンポーネントのプロパティを現在のユーザーロケールに応じて変更できます。

{
    "type": "Text",
    "color": "${@localizedColorResource}",
    "text": "${@welcome}"
}

スタイルの評価を利用して、ローカライズされたAPLスタイル定義を使用することで、スタイル付きコンポーネントプロパティの組み合わせを現在のユーザーロケールに応じて変更できます。また、ローカライズされたスタイルプロパティ値をリソースに配置し、スタイルがそのリソースを参照するように設定することもできます。

{
  "type": "APL",
  "version": "2022.1",
  "styles": {
    "WelcomeTextStyle": {
      "values": [
        {
          "color": "green",
          "fontSize": "@welcomeTextSize"
        },
        {
          "when": "${environment.lang != 'ja-JP'}",
          "color": "red",
          "fontWeight": 200
        }
      ]
    }
  },
  "mainTemplate": {
    "items": [
      {
        "type": "Text",
        "style": "WelcomeTextStyle",
        "text": "${@welcome}"
      }
    ]
  }
}

APLテンプレートにすべてのロケールのスタイル定義が含まれないようにするには、翻訳済み文字列をロケール固有のAPLリソースパッケージで指定すると同じアプローチを採用し、リソース文字列、スタイル、レイアウトなどのローカライズされたアセットのみを提供する専用のAPLパッケージにスタイル定義を含めます。この場合、ローカライズされたAPLパッケージのURLパスは、スキルによってRenderDocumentディレクティブの応答にハードコードされます。

return {
    type: 'Alexa.Presentation.APL.RenderDocument',
    token: 'myToken',
    document: {
        type: 'APL',
        version: '2022.1',
        import: [
            {
                name: "my-local-assets",
                source: 'https://path.to/my/local-assets-for-' + locale + '.json',
                version: '1.0'
            }
        ],
        mainTemplate: {
            items: [
                {
                    type: "Text",
                    style: "WelcomeTextStyle",
                    text: "${@welcome}"
                }
            ]
        }
    }
}

レイアウトをローカライズする

スタイルの外観だけにとどまらず、コンポーネント構造全体にローカライズされた変更を適用する場合は、APLレイアウトが最適です。APLテンプレートデザインからローカライズの対象となるコンポーネント構造を抽出し、APLレイアウトとして定義します。詳細については、APL技術資料ページのAPLレイアウトを参照してください。最初の選択肢は、APLテンプレートに提供した別のAPLパッケージからインポートされたAPLレイアウトについて、レイアウト定義全体を上書きすることです。たとえば、レイアウト、スタイル、リソースなどのデフォルトアセットを使用してAPLパッケージを作成します。次に、ローカライズされたアセットを含む2つ目のAPLパッケージをインポートし、同じレイアウト名のローカライズ版を提供することで、レイアウトを選択的に上書きします。スキルコードでは、以下のコード例のようなRenderDocumentディレクティブを作成します。

return {
    type: 'Alexa.Presentation.APL.RenderDocument',
    token: 'myToken',
    document: {
        type: 'APL',
        version: '2022.1',
        import: [
            {
                name: "my-global-assets",
                source: 'https://path.to/my/global-assets.json',
                version: '1.0'
            }
            {
                name: "my-local-assets",
                source: 'https://path.to/my/local-assets-for-' + locale + '.json',
                version: '1.0'
            }
        ],
        mainTemplate: {
            items: [
                {
                    type: "MyWeatherInfoLayout"
                }
            ]
        }
    }
}

どちらのAPLパッケージにも、MyWeatherInfoLayoutというレイアウトが含まれています。ローカライズ版の2つ目のAPLパッケージで1つ目のAPLパッケージのレイアウトが上書きされるため、ローカルなユーザーのニーズに応じたレイアウトがAPLテンプレートによってレンダリングされます。

{
  "type": "APL",
  "version": "2022.1",
  "layouts": {
    "MyWeatherInfoLayout": {
      "items": [
        ...
      ]
    }
  }
}

APLレイアウトには、ローカルなニーズの影響を完全には受けない複雑なコンポジットが含まれる傾向があります。場合によっては、ローカライズされたAPLパッケージのレイアウト全体を複製して上書きするよりも、グローバルなレイアウト定義を拡張して軽微な変更を適用する方がよいこともあります。そのような必要性がある場合は、レイアウトの影響を受ける部分を抽出して独自のローカライズ可能なレイアウトとして定義し、全体的な複製・上書きを行わないグローバルレイアウト内にネストします。以下の例のように、MyWeatherInfoLayoutを個々のパーツに分割して、選択的にローカライズすることができます。

{
    "type": "APL",
    "version": "2022.1",
    "layouts": {
      "MyTemperatureForecastLayout": {
        ...
      }  
      "MyForecastPanelLayout": {
        "items": [
            ...,
            {
              "type": "MyTemperatureForecastLayout"
            },
            ...
        ]
      }  
      "MyWeatherInfoLayout": {
        "items": [
          ...,
          {
            "type": "MyForecastPanelLayout"
          },
          ...
        ]
      }
    }
}

ローカライズされたAPLパッケージでは、MyForecastPanelLayoutまたはMyTemperatureForecastLayoutのいずれかを上書きすることで、レイアウト全体の特定の部分のみをローカライズできます。これにより、ローカライゼーション目的で上書きを行う場合に、複製するコードの量を削減できます。

機能的動作をローカライズする

APLテンプレートは、ユーザーがAPLコマンドを使用してボタン、スライドバー、スクロールビューなどのUI要素を操作するための機能を実装します。詳細については、APL技術資料ページのAPLコマンドを参照してください。ほかのAPLコンポーネントと同様に、個々のコマンドとコマンドグループでは、現在のユーザーロケールなどの特定の条件に基づいて、動作を動的に変更することができます。これにより、さまざまなユーザーロケールに応じてUIの動作を変更できます。

{
    "type": "TouchWrapper",
    "onPress": [
        {
            "type": "WelcomeShowUS",
            "when": "${environment.lang == 'ja-JP'}"
        },
        {
            "type": "WelcomeShowROW",
            "when": "${environment.lang != 'ja-JP'}"
        }
    ]
}

ローカライズされたAPLコマンドを使用することで、APLのリソース、スタイル、条件付きプロパティ値の割り当てだけでは対応できない、APLコンポーネントの特定のローカライズニーズにも対応できるようになります。たとえば、APL Textコンポーネントに表示する翻訳済み文字列には、商品タイトルなどの動的なデータソース値が含まれています。言語によっては、商品タイトルが文内の別の場所にある場合もあります。APLコンポーネントのonMountイベントハンドラーでAPLコマンドを使用すると、文字列の動的な連結が可能になります。

{
  "type": "APL",
  "version": "2022.1",
  "commands": {
    "ConstructSelectText": {
      "parameters": [
        {
          "name": "productCategory"
        }
      ],
      "commands": {
        "type": "SetValue",
        "property": "text",
        "value": "${productCategory}から選択してください"
      }
    }
  },
  "mainTemplate": {
    "parameters": [
      "myData"
    ],
    "items": [
      {
        "type": "Text",
        "text": "${@pleaseWait}",
        "onMount": {
          "type": "ConstructSelectText",
          "productCategory": "${myData.productCategory}"
        }
      }
    ]
  }
}

ユーザー定義のConstructSelectTextは、「${productCategory}から選択してください」というテキストを作成するロジックをカプセル化しています。ドイツ語などのその他の言語では、${productCategory}の動的な値は、異なる方法で文に埋め込まれます。このニーズを反映するために、ドイツ語のユーザーロケール向けにローカライズされるAPLパッケージでは、以下のコード例に示すように、ConstructSelectTextコマンドを上書きします。

"ConstructSelectText": {
    "parameters": [
        {
            "name": "productCategory"
        }
    ],
    "commands": {
        "type": "SetValue",
        "property": "text",
        "value": "Bitte wählen Sie ${productCategory} aus."
    }
}

このページは役に立ちましたか？

フィードバックを送信

最終更新日: 2025 年 11 月 26 日

APLテンプレートを効率的にローカライズする

APLリソースをローカライズする

翻訳済み文字列をAPLテンプレートにハードコードする

翻訳済み文字列をデータソースで指定する

翻訳済み文字列をAPLリソース文字列として指定する

翻訳済み文字列をAPLリソースパッケージで指定する

翻訳済み文字列をロケール固有のAPLリソースパッケージで指定する

スタイルをローカライズする

レイアウトをローカライズする

機能的動作をローカライズする

関連トピック