Skip to content

Better localization docs for dashboard elements and field picker customization #735

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
zdrawku wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Better localization docs for dashboard elements and field picker customization #735

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ed73464
Enhance localization documentation for dashboard elements and field p…
zdrawku Jul 29, 2026
5c9732c
Update localization documentation to clarify field filter behavior
zdrawku Jul 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 29 additions & 1 deletion docs/web/localizing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,35 @@ RevealSdkSettings.localizedStringsProvider = function (element, context) {

![](images/localization-test-visualization-fields.jpg)

You can use this way to customize the localization behavior for the following element types: `DashboardFilterTitle`, `DashboardTitle`, `FieldLabel`, `VisualizationFieldLabel` and `VisualizationTitle`.
`localizedStringsProvider` is a dashboard-model pass: it walks the dashboard title, global filters, and widgets that are already part of the dashboard, and only ever sees elements that have been bound into that model. It does not hook into UI surfaces that are populated directly from a data source's schema, such as the field picker shown when adding a dashboard filter. The table below shows where each element type is actually raised.

@PVillarmarzo PVillarmarzo Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this wording is a bit too implementation-specific and absolute for the public docs. localizedStringsProvider is also invoked for supported elements while creating visualizations, so describing it as a “dashboard-model pass” that “only ever sees” already-bound elements may be misleading.

Could we describe the observable behavior instead? For example:

“localizedStringsProvider is invoked for supported dashboard and visualization titles and field metadata. It is not invoked for the schema fields returned specifically for the dashboard-filter field picker.”


| Element type | Raised for |
| --- | --- |
| `DashboardTitle` | The dashboard's title |
| `DashboardFilterTitle` | The title of a global (dashboard) filter that has already been added to the dashboard |
| `VisualizationTitle` | A visualization's title |
| `FieldLabel` | A field that is bound to the dashboard but not (yet) part of any visualization, nor used in a summarization definition |

@PVillarmarzo PVillarmarzo Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The FieldLabel description may be too narrow. In the current implementation, it can be raised for fields in the tabular field collection even when those fields are also used by the visualization.

Suggested wording:
“A source field available to a tabular visualization. This can include fields that are not currently selected by the visualization.”

| `VisualizationFieldLabel` | A field that is being used in a visualization, and can have an aggregation applied to it |

@PVillarmarzo PVillarmarzo Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The VisualizationFieldLabel description may be incomplete. It is raised for fields or calculated columns used by a visualization, including non-measure fields, which report Auto as their aggregation type.

Suggested wording:
“A field or calculated column used by a visualization. The element includes its aggregation type, which is Auto for non-measure fields.”


In other words, `FieldLabel` and `VisualizationFieldLabel` only cover fields that are already bound into a dashboard or a visualization — they are not raised for schema-driven pickers such as the field list shown when adding a dashboard filter. See [Localizing dashboard filter fields](#localizing-dashboard-filter-fields) below for how to localize that list.

## Localizing dashboard filter fields {#localizing-dashboard-filter-fields}

When you choose **Add Dashboard Filter** and then **Select a field**, the field list shown there is populated directly from the data source's schema, not from the dashboard model. Because `localizedStringsProvider` only processes elements already bound into the dashboard, it is never invoked for this list, and returning a translation from it has no effect on the field picker.

To customize the field names shown in this list, use the `revealView.onFieldsInitializing` event instead. It is raised whenever a field list is being populated from a data source's schema — including the dashboard filter field picker — and lets you rename, remove, or reorder the fields shown.

@PVillarmarzo PVillarmarzo Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“Whenever a field list is being populated” seems too absolute. Could we limit this to the known supported surfaces: the visualization editor after selecting a data source and the tabular dashboard-filter field picker?


```js
revealView.onFieldsInitializing = function (args) {
var editedFields = args.fields;
// change name to show to Spend field to Spent
var fieldToChange = editedFields.find(f => f.name == "Spend");
if (fieldToChange) { fieldToChange.label = "Spent"; }
args.fields = editedFields;
}
```

Once a field is selected as a dashboard filter, the filter control continues to display the label assigned through `onFieldsInitializing`, consistent with what was shown in the picker.

## Example: Selecting the locale from a combo box

Expand Down
30 changes: 29 additions & 1 deletion i18n/ja/docusaurus-plugin-content-docs/current/web/localizing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,35 @@ RevealSdkSettings.localizedStringsProvider = function (element, context) {

![](images/localization-test-visualization-fields.jpg)

この方法を使用して、要素タイプ `DashboardFilterTitle`、`DashboardTitle`、`FieldLabel`、`VisualizationFieldLabel`、および `VisualizationTitle` のローカライズ動作をカスタマイズできます。
`localizedStringsProvider` はダッシュボード モデルに対するパスです。ダッシュボードのタイトル、グローバル フィルター、およびすでにダッシュボードの一部になっているウィジェットを走査し、そのモデルにバインドされている要素のみを認識します。データ ソースのスキーマから直接生成される UI 要素、たとえばダッシュボード フィルターを追加する際に表示されるフィールド ピッカーには、このイベントはフックされません。以下の表は、各要素タイプが実際にどこで発生するかを示しています。

| 要素タイプ | 発生するタイミング |
| --- | --- |
| `DashboardTitle` | ダッシュボードのタイトル |
| `DashboardFilterTitle` | すでにダッシュボードに追加されているグローバル (ダッシュボード) フィルターのタイトル |
| `VisualizationTitle` | ビジュアライゼーションのタイトル |
| `FieldLabel` | ダッシュボードにバインドされているが、まだどのビジュアライゼーションにも含まれておらず、サマリー定義でも使用されていないフィールド |
| `VisualizationFieldLabel` | ビジュアライゼーションで使用されている、集計が適用され得るフィールド |

つまり、`FieldLabel` と `VisualizationFieldLabel` は、すでにダッシュボードやビジュアライゼーションにバインドされているフィールドのみをカバーします。ダッシュボード フィルターを追加する際に表示されるフィールド一覧のような、スキーマ駆動のピッカーに対しては発生しません。このフィールド一覧をローカライズする方法については、以下の[ダッシュボード フィルターのフィールドをローカライズする](#localizing-dashboard-filter-fields)を参照してください。

## ダッシュボード フィルターのフィールドをローカライズする {#localizing-dashboard-filter-fields}

**ダッシュボード フィルターの追加** を選択し、続けて **フィールドを選択** を選ぶと表示されるフィールド一覧は、ダッシュボード モデルではなく、データ ソースのスキーマから直接生成されます。`localizedStringsProvider` はダッシュボードにすでにバインドされている要素しか処理しないため、この一覧に対しては呼び出されず、ここから翻訳を返してもフィールド ピッカーには反映されません。

この一覧に表示されるフィールド名をカスタマイズするには、代わりに `revealView.onFieldsInitializing` イベントを使用します。このイベントは、ダッシュボード フィルターのフィールド ピッカーを含め、データ ソースのスキーマからフィールド一覧が生成されるたびに発生し、表示されるフィールドの名前変更、削除、並べ替えができます。

```js
revealView.onFieldsInitializing = function (args) {
var editedFields = args.fields;
// Spend フィールドの表示名を Spent に変更する
var fieldToChange = editedFields.find(f => f.name == "Spend");
if (fieldToChange) { fieldToChange.label = "Spent"; }
args.fields = editedFields;
}
```

フィールドがダッシュボード フィルターとして選択された後も、フィルター コントロールはピッカーに表示されていたものと変わらず、`onFieldsInitializing` で設定したラベルを引き続き表示します。

## 例: コンボ ボックスからロケールを選択する

Expand Down
30 changes: 29 additions & 1 deletion i18n/ja/docusaurus-plugin-content-docs/version-1.8.4/web/localizing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,35 @@ $.ig.RevealSdkSettings.localizedStringsProvider = function (element, context) {

![](images/localization-test-visualization-fields.jpg)

この方法を使用して、要素タイプ `DashboardFilterTitle`、`DashboardTitle`、`FieldLabel`、`VisualizationFieldLabel`、および `VisualizationTitle` のローカライズ動作をカスタマイズできます。
`$.ig.RevealSdkSettings.localizedStringsProvider` はダッシュボード モデルに対するパスです。ダッシュボードのタイトル、グローバル フィルター、およびすでにダッシュボードの一部になっているウィジェットを走査し、そのモデルにバインドされている要素のみを認識します。データ ソースのスキーマから直接生成される UI 要素、たとえばダッシュボード フィルターを追加する際に表示されるフィールド ピッカーには、このイベントはフックされません。以下の表は、各要素タイプが実際にどこで発生するかを示しています。

| 要素タイプ | 発生するタイミング |
| --- | --- |
| `DashboardTitle` | ダッシュボードのタイトル |
| `DashboardFilterTitle` | すでにダッシュボードに追加されているグローバル (ダッシュボード) フィルターのタイトル |
| `VisualizationTitle` | ビジュアライゼーションのタイトル |
| `FieldLabel` | ダッシュボードにバインドされているが、まだどのビジュアライゼーションにも含まれておらず、サマリー定義でも使用されていないフィールド |
| `VisualizationFieldLabel` | ビジュアライゼーションで使用されている、集計が適用され得るフィールド |

つまり、`FieldLabel` と `VisualizationFieldLabel` は、すでにダッシュボードやビジュアライゼーションにバインドされているフィールドのみをカバーします。ダッシュボード フィルターを追加する際に表示されるフィールド一覧のような、スキーマ駆動のピッカーに対しては発生しません。このフィールド一覧をローカライズする方法については、以下の[ダッシュボード フィルターのフィールドをローカライズする](#localizing-dashboard-filter-fields)を参照してください。

## ダッシュボード フィルターのフィールドをローカライズする {#localizing-dashboard-filter-fields}

**ダッシュボード フィルターの追加** を選択し、続けて **フィールドを選択** を選ぶと表示されるフィールド一覧は、ダッシュボード モデルではなく、データ ソースのスキーマから直接生成されます。`$.ig.RevealSdkSettings.localizedStringsProvider` はダッシュボードにすでにバインドされている要素しか処理しないため、この一覧に対しては呼び出されず、ここから翻訳を返してもフィールド ピッカーには反映されません。

この一覧に表示されるフィールド名をカスタマイズするには、代わりに `revealView.onFieldsInitializing` イベントを使用します。このイベントは、ダッシュボード フィルターのフィールド ピッカーを含め、データ ソースのスキーマからフィールド一覧が生成されるたびに発生し、表示されるフィールドの名前変更、削除、並べ替えができます。

```js
revealView.onFieldsInitializing = function (args) {
var editedFields = args.fields;
// Spend フィールドの表示名を Spent に変更する
var fieldToChange = editedFields.find(f => f.name == "Spend");
if (fieldToChange) { fieldToChange.label = "Spent"; }
args.fields = editedFields;
}
```

フィールドがダッシュボード フィルターとして選択された後も、フィルター コントロールはピッカーに表示されていたものと変わらず、`onFieldsInitializing` で設定したラベルを引き続き表示します。

## 例: コンボ ボックスからロケールを選択する

Expand Down
30 changes: 29 additions & 1 deletion versioned_docs/version-1.8.4/web/localizing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,35 @@ $.ig.RevealSdkSettings.localizedStringsProvider = function (element, context) {

![](images/localization-test-visualization-fields.jpg)

You can use this way to customize the localization behavior for the following element types: `DashboardFilterTitle`, `DashboardTitle`, `FieldLabel`, `VisualizationFieldLabel` and `VisualizationTitle`.
`$.ig.RevealSdkSettings.localizedStringsProvider` is a dashboard-model pass: it walks the dashboard title, global filters, and widgets that are already part of the dashboard, and only ever sees elements that have been bound into that model. It does not hook into UI surfaces that are populated directly from a data source's schema, such as the field picker shown when adding a dashboard filter. The table below shows where each element type is actually raised.

| Element type | Raised for |
| --- | --- |
| `DashboardTitle` | The dashboard's title |
| `DashboardFilterTitle` | The title of a global (dashboard) filter that has already been added to the dashboard |
| `VisualizationTitle` | A visualization's title |
| `FieldLabel` | A field that is bound to the dashboard but not (yet) part of any visualization, nor used in a summarization definition |
| `VisualizationFieldLabel` | A field that is being used in a visualization, and can have an aggregation applied to it |

In other words, `FieldLabel` and `VisualizationFieldLabel` only cover fields that are already bound into a dashboard or a visualization — they are not raised for schema-driven pickers such as the field list shown when adding a dashboard filter. See [Localizing dashboard filter fields](#localizing-dashboard-filter-fields) below for how to localize that list.

## Localizing dashboard filter fields {#localizing-dashboard-filter-fields}

When you choose **Add Dashboard Filter** and then **Select a field**, the field list shown there is populated directly from the data source's schema, not from the dashboard model. Because `$.ig.RevealSdkSettings.localizedStringsProvider` only processes elements already bound into the dashboard, it is never invoked for this list, and returning a translation from it has no effect on the field picker.

To customize the field names shown in this list, use the `revealView.onFieldsInitializing` event instead. It is raised whenever a field list is being populated from a data source's schema — including the dashboard filter field picker — and lets you rename, remove, or reorder the fields shown.

```js
revealView.onFieldsInitializing = function (args) {
var editedFields = args.fields;
// change name to show to Spend field to Spent
var fieldToChange = editedFields.find(f => f.name == "Spend");
if (fieldToChange) { fieldToChange.label = "Spent"; }
args.fields = editedFields;
}
```

Once a field is selected as a dashboard filter, the filter control continues to display the label assigned through `onFieldsInitializing`, consistent with what was shown in the picker.

@PVillarmarzo PVillarmarzo Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the SDK fix will not be backported to 1.8.4, this statement should not be included in the 1.8.4 documentation. The versioned docs should reflect the actual behavior of that release. The onFieldsInitializing guidance for the picker entries is still valid, but the selected Field value will continue to display the raw field name in 1.8.4.


## Example: Selecting the locale from a combo box

Expand Down
Loading