局所化

PowerPortalsProは、すべてのユーザー向けテキストに対してJSONベースのローカライゼーションシステムを使用しています。これにはコンポーネントラベル、テーブル名や列名、ビュー名、検証メッセージ、アプリケーション固有の文字列が含まれます。Blazorスタックは IStringLocalizerで読み、Reactスタックは useT() フックを通して読みます。両方のスタックは同じJSON形状を消費します。 app.en.json に一度作成された文字列が両方のスタックを駆動し(Dataverseメタデータ由来の tables.* 文字列などの共有リソースファイルも自動的に両方に流れます)。

ローカリゼーションファイル

ローカライズはサーバープロジェクトの localization ディレクトリにJSONファイルが配置されることで行われます。ファイルは命名規則 name.{culture}.json に従います(例: app.en.json、 app.fr.json)。同じJSON形状が、Reactスタック(ランタイム時にローカライザープロバイダーが取得)とBlazorスタック(起動時に IStringLocalizerが読み取る)の両方を駆動します。

反応してください

React側では、ローカライザーは<PowerPortalsProProvider>によって自動マウントされており、マウント時やロケーション変更のたびにアクティブなロケーションのバンドルを/localizations/...から取得する<DefaultLocalizerProvider>が含まれています。明示的なローカレ切り替え状態(URLパス、ASP.NET カルチャークッキー、またはデフォルトでnavigator.language)を知りたい場合は、プロバイダーを<LocaleProvider>でラップします。バンドルが解決される前の短いウィンドウ中にユーザーが見る文字列は、生のキーとしてレンダリングされます。プロバイダーはフェッチが着地するとすぐに本物のストリングを交換します。

ブレイザー

サーバーの Program.cs にローカリゼーションディレクトリを AddLocalizationDirectoryで登録します。フレームワークは起動時にそれらを読み取り、解決された IStringLocalizer やDI IStringLocalizer<T> をバックアップします。

HTMLローカリゼーションファイル

メールテンプレートのような長文コンテンツでは、HTML文字列をJSONに埋め込む代わりにスタンドアロンのHTMLファイルを使うことができます。ファイル名は、 {key-path}.{culture}.html形式で完全なローカリゼーションキーパスと文化をエンコードします。

ファイル名の各ドット区切られたセグメントは、ローカライゼーションキー階層のレベルに対応します。最後から2番目のセグメントは文化コード(例: en、 fr)です。これらのファイルは AddLocalizationDirectoryに登録されている同じローカリゼーションディレクトリに入れてください。

例えば、以下のファイル構造があります:

このファイルemails.signup-confirmation.body.en.html、en文化のローカライゼーションキーemails.signup-confirmation.bodyにマッピングされます。これは、HTMLの内容がJSONファイルのキーパスにある文字列値として存在するのと同等です。

ファイル名に対応する同じ IStringLocalizer キーを使って内容を取得します。HTMLコンテンツはローカライズされた文字列として返され、 ToMarkupString()でレンダリング可能です。

テーブルラベルおよびカラムラベル

テーブルおよびカラムの表示名、説明、ビューラベルは、 tables.{tableName}.label、 tables.{tableName}.columns.{columnName}.label、 tables.{tableName}.views.{viewId}.labelの規則を用いてローカリゼーションファイルから自動的に解決されます。

注記

デフォルトでは、フレームワークはDataverse環境 内のすべての テーブルのメタデータを読み込みます。複数言語をサポートするポータルでは、 LocalizeAllAvailableTables = false を設定し、 AddTableToLocalize で実際に使うテーブルのみを登録すべきです。すべてのテーブルを読み込むと起動ウォームアップが遅くなり、表示されないラベルで文字列キャッシュがいっぱいになります(インストール言語ごとに支払われるコストです)。UIにラベルが表示されているすべてのテーブル(グリッド、フォーム、サブグリッド、チャート)を登録してください。ローカライズされていない表示テーブルはラベルの代わりに生のキーをレンダリングします。 account、 contact、 adx_externalidentity はデフォルトで含まれています。

ラベルを見る

グリッドビューセレクターのドロップダウンにあるビューラベルは tables.{tableName}.views.{viewId}.labelの下にローカライズされており、 {viewId} はDataverseに保存されたビューのGUID(括弧なし、小文字)です。これは MainGrid ビューセレクターと SubGrid ビューセレクターの両方に当てはまります。

注記

CustomViewDefinitionsで定義されたカスタムビューでも同じ慣例が適用されます — カスタムビューのGUIDをキーとして使用します。ローカライズされたラベルが見つからない場合は、GridViewDefinitionやDataverseメタデータのビュー名をフォールバックとして使います。

列ヘッダーを見る

グリッドに表示される列ヘッダーはフォールバックパターンで解決されます。システムはまずtables.{tableName}.views.{viewId}.columns.{columnName}.labelでビュー固有の列ラベルを探します。見つからない場合は、tables.{tableName}.columns.{columnName}.labelのテーブルレベルの列ラベルに戻されます。ツールチップも同じパターンで、.labelではなく.descriptionを使います。

これにより、特定のビューの列のヘッダーを上書きしても、他のビューや編集者でのラベルに影響を与えません。

注記

リンクされたエンティティ(例: contact.emailaddress1)からの列の場合、キー内の列名はエイリアスで先頭に付く形式が使われます。ビュー固有のラベルが見つからない場合は、リンクされた列名とその親列ラベル(例:「Email (Primary Contact)」)からラベルを作成します。

選択(オプションセット)ラベル

選択列のオプションラベルは、オプションセットがテーブルスコープかグローバルかによって異なるローカライズされます。

テーブルスコープ選択

テーブルスコープの選択肢は tables.{tableName}.choices.{choiceLogicalName}.values.{value}.labelのローカライズされています。選択論理名はテーブル名(例: account_accountcategorycode)で接頭辞を付けます。

グローバル・チョイス

グローバル選択(複数のテーブルで共有されるオプションセット)は、 choices.{choiceLogicalName}.values.{value}.labelのルートレベルで、テーブルセクションの外にローカライズされています。

注記

ChoiceEditおよびMultiSelectChoiceEditコンポーネントは、カラムメタデータのIsGlobal特性に基づいて、正しい場所から選択ラベルを自動的に解決します。

ローカライザーの注入

文字列ローカライザーを注入する方法は2つあります:

• IStringLocalizer — すべてのローカライゼーションキーにグローバルにアクセスできる。テーブルラベルや共有文字列、 GetPrefixedLocalizer メソッドが必要なときに使ってください。
• IStringLocalizer<T> — 特定のコンポーネントタイプにスコープが設定されています。キーはJSONファイル内のコンポーネントの名前空間パス(例: components.{Namespace}.{ComponentName}.{key})に基づいて相対的に解決されます。

コンポーネントスコープキー

IStringLocalizer<T>を使用する場合、キーはコンポーネントの名前空間とクラス名に基づいて解決されます。例えば、Pages.Editors.TextEdit.TextEditDemoPageのコンポーネントはJSONのcomponents.{AssemblyName}.Pages.Editors.TextEdit.TextEditDemoPage.{key}キーを解決します。

プレフィックス・ローカライザー

GetPrefixedLocalizerを使って、すべてのキー検索に自動的にプレフィックスを付けるサブローカライザーを作成します。これは、同じセクションの多くのキーを使うコンポーネントで重複するキープレフィックスを避けるのに役立ちます。

ローカライズされた文字列におけるHTML

ローカライズド文字列にはHTMLマークアップを含めることができます。 ToMarkupString() 拡張メソッドを使ってRazorテンプレートで MarkupString としてレンダリングしてください。

最適なマッチを見つける

FindLocalizedStringを使って候補リストから最初の一致キーを調べます。これは、まず特定のキーを試してからより一般的なキーに戻すフォールバックパターンに役立ちます。

React側では useT() 、文字列が欠落すると生キーを返します。 t(key) !== key 「このキーは解決されましたか?」というチェックで、フォールバックウォークオンを構築します。複数の通話サイトで必要なときには、パターンをヘルパーで包んでおきましょう。

引数補間

弦には位置の {0}、 {1}、...ルックアップ時に置き換えられるプレースホルダー。Blazorはargをパラメータ配列として IStringLocalizerに渡します。Reactはそれらを t()に2つ目の引数として渡します。プレースホルダー内のオプションフォーマット指定子({0:N0}、 {1:yyyy-MM-dd})はBlazorの String.Format パイプラインでのみ尊重されます。Reactの場合は、値を渡す前に Intl.NumberFormat / Intl.DateTimeFormat で事前フォーマットします。

イーガーローディング(React)

キャッシュミス時には、Reactスタックがリソースごとに1回のデボウンスバッチ(約75msごとに1バッチ)を怠惰に取得し、文字列が着くと消費コンポーネントを再レンダリングします。生キーの一瞬のフラッシュを避けるために、ページに必要な接頭辞を useLocalization([...])で最初に宣言するか、上位の <LocalizationBoundary> ラッパーで解決されるまでレンダリングを控えましょう。完全なパターンについてはLocalizationBoundaryページをご覧ください。