Skip to content

Document filter label translation in embed language maps #1201

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

Merged
magnew merged 1 commit into from
Aug 31, 2026
Merged

Document filter label translation in embed language maps #1201

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
18 changes: 14 additions & 4 deletions embed/react-sdk.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1231,7 +1231,7 @@ The React SDK has two translation props, split by what they translate:

| Prop | Translates | Shape |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `contentOverrides` | **Your content**: dashboard and chart names, tile titles, markdown, labels | `LanguageMap`, slug-keyed, generated with `lightdash download --language-map` |
| `contentOverrides` | **Your content**: dashboard and chart names, tile titles, markdown, custom filter labels | `LanguageMap`, slug-keyed, generated with `lightdash download --language-map` |
| `uiOverrides` | **Lightdash's UI**: filter operators and inputs, the filter popover, date zoom, tile menus, export buttons | Flat `{ key: string }` map with a fixed, typed key set |

There is no locale setting and no bundled language packs. Your app owns locale state and passes the translated strings for the language it wants. Anything you don't override renders in the built-in English.
Expand All @@ -1240,7 +1240,7 @@ Both props are accepted by `Lightdash.Dashboard`, `Lightdash.DashboardBuilder`,

### Translating your content with `contentOverrides`

`contentOverrides` translates the content you author in Lightdash: dashboard names and descriptions, tile titles, chart names, axis labels, series names, and markdown content.
`contentOverrides` translates the content you author in Lightdash: dashboard names and descriptions, tile titles, chart names, axis labels, series names, markdown content, and the custom labels you've set on dashboard filters.

Recommended tools:

Expand Down Expand Up @@ -1271,6 +1271,10 @@ dashboard:
sdk-dash:
name: SDK dashboard demo
description: "A dashboard demonstrating SDK features"
filters:
labels:
Completed orders: Completed orders
Order period: Order period
tiles:
- type: markdown
properties:
Expand All @@ -1285,6 +1289,12 @@ dashboard:

These translation maps can be imported into tools like Locize to begin translation.

**Filter labels.** If a dashboard has filters with custom labels, the map includes a `filters.labels` block mapping each source label to its translation. Replace the right-hand values with the translated strings. Entries are keyed by the source label rather than by position, so translations keep working when filters are reordered, added, or removed. Renaming a filter label in Lightdash invalidates its entry, and the filter pill falls back to the untranslated label until you regenerate the map. Filters without a custom label show the field name, which isn't translatable.

<Note>
Translations only change what viewers see. When someone saves an embedded dashboard in edit mode, Lightdash keeps the source filter labels, so the saved dashboard is unchanged for other languages.
</Note>

#### Runtime translation

At runtime, pass a translation object to the SDK's `contentOverrides` prop. We suggest using `i18Next` to load translations:
Expand Down Expand Up @@ -1829,13 +1839,13 @@ Re-mounting the component on language change (the `key` prop) is the simplest wa

| Surface | Translatable with |
| -------------------------------------------------------------------------------------------------- | ------------------ |
| Dashboard and chart names, descriptions, tile titles, axis labels, series names, markdown content | `contentOverrides` |
| Dashboard and chart names, descriptions, tile titles, axis labels, series names, markdown content, custom filter labels | `contentOverrides` |
| Filter operators and inputs, the filter popover, date zoom, tile menus, export and print buttons | `uiOverrides` |

Not translatable:

- **Data from your warehouse** – string values in charts, dimension values, and raw table data render as they exist in your database
- **Field and table names** – dimension and metric labels shown on filter pills and in the field picker come from your dbt schema
- **Field and table names** – dimension and metric names shown in the field picker, and on filter pills without a custom label, come from your dbt schema
- **Date picker internals** – month and weekday names inside calendar popups render in English
- **Data formatting** – numbers, dates, and currencies render per chart config
- **Editor-only UI** – dashboard edit mode is not translated
Expand Down
Loading