Why teams need Apache Superset translations and localization
If your analysts or regional offices work in a language other than English, Superset's translation and localization work decides whether they can read menus, chart labels and dashboard text in their own language, and whether dates and numbers follow local conventions. In practice, localization covers three areas: the UI strings that Superset shows to users, the date and number formatting that changes how values read, and the decision about which terms should stay in English. Each area needs its own check, because a translated menu next to an untranslated SQL keyword or an unfamiliar date order creates confusion that a language pack alone does not fix.
Superset is an Apache Software Foundation project released under the Apache-2.0 license, and the project has no paid edition. No vendor will translate your instance for you as part of a license, so the work falls to your team or to an implementation partner. That means someone has to decide which languages to support, how translation builds reach your container images, who reviews terminology, and how new upstream releases will be merged into your localized build. Before committing, confirm the state of each target language against the upstream translation files for the version you run, because coverage varies and this page does not assert which languages are complete.
The translation guide in the Superset developer documentation sets the boundary for what should not be translated: product names, strings that programs read such as SQL keywords, and terms users see in their own tools. Those strings are listed in a file in the repository, so your reviewers have a fixed reference to work from. Treating that list as the starting point for your terminology review, rather than translating every visible string by default, is the decision that most affects whether localized dashboards stay usable. Plan this review before rollout, and assign an owner who can approve terms for each language.
Localization choices and when each fits
This table compares four ways to run Superset in another language, from using upstream builds as shipped to contributing missing terms back to the project. Read each row against your team's upgrade cadence and how many locales you need, since the ongoing cost of each option depends on who owns the translation files after every release. The main takeaway is that the cheapest option at launch is often the most expensive to keep current.
| Option | Effort drivers | Ownership on each upgrade | When it fits |
|---|---|---|---|
| Upstream translation builds as shipped | Low setup; only the locales already bundled with the release are available | Upstream project maintains the translations; you test the bundled languages after each upgrade | Teams that need a supported language already in the release and accept upstream term choices |
| Custom image with selected locales | Build pipeline changes, translation compile step and testing of each chosen locale | Your team rebuilds the image on every upgrade and re-checks translated screens and formats | Teams that need a specific set of locales while keeping an upstream-based image |
| Private language pack | Ongoing term maintenance, reviewer time and reconciliation with new upstream strings | Your team owns every new or changed string after each release, so upgrades add translation work | Organizations with approved internal terminology that upstream will not adopt, and staff to review changes |
| Contributing terms upstream | Writing and reviewing translations to the project's standards, plus response time from maintainers | Shared with the community once merged, so the fix reaches later releases without local patches | Teams with reviewers who can contribute and want missing terms maintained for everyone |
| Keeping product names and program-read strings in English | Requires a review pass to confirm the do-not-translate list is respected in any option | Must be rechecked on each upgrade because new strings may be added | Applies to every option; confirm against the translation guide's do-not-translate list before translating |
How to enable a translated Superset build step by step
This sequence takes a Superset deployment from a chosen release and locale list to a verified translated interface in staging. Each step ends with a check you can repeat before users see the change, so the output is a documented, tested locale configuration.
Confirm target version and locales
The owner is your platform lead, with a product owner who signs off on languages. Pick the exact Superset release you will run and confirm it on the project's releases page, noting whether it is a stable release or a pre-release. List each locale your users need and confirm with your translators which ones the release supports. Done when a signed-off record names the version, the locales, and the person accountable for each.
Choose the image or PyPI path
The platform engineer decides whether translations reach users through a container image your team builds or through a PyPI installation. Read the installation documentation for your chosen path and confirm where the translation files are compiled and how the language list is passed in. Keep the build definition in version control so the choice is repeatable. Done when the path is written down and a test build lists the compiled locale files for each language from step one.
Enable the translation build
The platform engineer turns on the translation step in the build and sets the language list it includes, using the settings described in the configuration documentation for your release. Run the build from a clean state so no old catalogs carry over. Check the build log for the translation step and inspect the artifact to confirm compiled catalogs exist for every locale from step one. Done when a clean build completes and each expected locale file is present.
Set default and per-user locale
The platform engineer sets the instance default locale in
superset_config.py, following the configuration documentation, and deploys the staging instance with that file. Per-user language is set on each account, and the test below confirms how it interacts with the default in your release. Test with two accounts: one with no language preference and one with a language set. Done when the account with no preference loads the default locale and the second account keeps its own language after sign-out and sign-in.Verify UI strings and formats in staging
The QA lead checks the staging instance in each locale, covering the login page, navigation, the SQL Lab editor, the chart builder and a sample dashboard. Use a fixed test dataset with known dates and decimal and thousands values, then compare the rendered output with the formats your locale standard expects. Capture screenshots for the record. Done when every page on the list has been reviewed in each locale, the test values display as expected, and any gaps are logged.
Confirm program-read strings are unchanged
The QA lead and an engineer compare the translation catalogs with the list of strings that must stay in English. That list is in
superset/translations/do-not-translate.txtin the source tree, and the translation guide explains which strings it covers. Run a SQL Lab query that uses keywords such as SELECT and WHERE in a non-English locale, then confirm it runs and returns the same results as in English. Done when no listed string is translated and the test query behaves the same in every locale.Log gaps and contribute missing terms
The translator or product owner records untranslated or awkward strings with screenshots and the page where each one appears. Missing terms that belong upstream go through the project's contribution process, so they do not stay only in a local patch. Document any local overrides so each upgrade can be checked against them. Done when the gap log is complete and every term has either an upstream proposal or a documented local decision.
Security and operational considerations for localized builds
A localized Superset is a custom build that you own after launch. The cards below cover the recurring work that keeps translations correct, reviewed and patched alongside the Superset version you run.
Patch translated images on every release
A build with translation files baked in is a custom image, so each Superset release means rebuilding and redeploying it, not just pulling the upstream image. Plan for every upstream security fix to reach your localized image on the same schedule as your standard image. Ask your build owner who rebuilds, who approves the rebuild and how a rollback returns you to the last working localized image.
Keep translations aligned with the running version
Translation files are tied to the strings of a specific Superset release. When the version changes, strings can be added, renamed or removed, so an older language pack can show gaps or stale wording. Check the translation set against the version you deploy in staging before each upgrade, and confirm which untranslated strings fall back to English.
Treat locale files as code
Locale files change how users read the application, so put them under the same change control as code: version control, pull requests, named reviewers and a recorded approval before merge. Keep the do-not-translate list in the translation guide under review as well, because a changed program-read string can break queries, filters or integrations without any visible error in the interface.
Review third-party translation edits
Translations often come from outside contributors, translation agencies or machine output. Do not merge edits you have not reviewed by a fluent speaker who knows Superset terminology. Unreviewed text is user-facing UI text, and a poorly chosen term for a permission, a data action or a warning can change how people act on dashboards. Record the source of each change so you can trace and reverse it.
Scan translated images like any other image
Translated text is rendered by the same web application that handles logins, queries and exports, so it does not sit outside your security review. Run the same supply chain checks on a localized image as on the standard one: pin base images, verify dependency sources, generate an SBOM and scan the final image for known vulnerabilities before it is deployed. Confirm your scanner also covers the language pack layers you added.
Test locale changes before production
Locale changes can alter layout, truncate labels and change date or number display in dashboards and reports. Test each localized build in staging with the same language settings your users choose, covering login, the main navigation, a sample of dashboards, exports and scheduled reports. Keep a written list of those checks so every rebuild runs the same test.
Questions buyers ask about Superset localization cost and effort
What drives the effort for adding a new language to Superset?
The main driver is how much of the interface and the surrounding product your users actually see, and how many strings need a reviewed translation. Effort grows with the number of screens your users touch, the amount of custom text you have added through branding, themes or plugins, and the number of people who must review each term. Date, number and currency formats add a smaller, separate piece of work because they need to match local conventions. Ask for a written count of the strings in scope, the languages covered, and whether custom text from your own extensions is included. Ask also who approves terms, because review cycles often take longer than the first pass of translation.
Can content owners translate Superset, or do developers need to be involved?
Content owners can translate and review terms, but a developer must still build the translations into your image and check the result in a running instance. Translators usually work from message catalogs and a glossary, which does not require code changes. Developers are needed to enable translation builds, add any custom strings from your own extensions, and confirm that the deployed image loads the right language files. Ask your team to name one person who owns the glossary and one reviewer per language, so that terms stay consistent across dashboards, alerts and reports.
How do Superset upgrades change translated strings?
Upgrades can add, rename or remove strings, which leaves some translations missing or outdated until someone translates the new text. Check the release notes and UPDATING.md for each target version before you upgrade, and plan a translation pass for new strings as part of the upgrade test in staging. Recurring work comes from this cycle, so budget for it as an ongoing cost rather than a one-time project. Ask the partner how they will compare catalogs between versions and how they will handle strings you customized yourself.
Will DeployOpen contribute missing terms upstream to the Superset project?
DeployOpen can prepare translation contributions for missing or improved terms, but acceptance is decided by the Apache Superset project, not by DeployOpen or your organization. The project's translation guide says that product names, strings that programs read, and terms users see in their own tools stay in English, and it lists those program-read strings in a file in the repository. Any upstream contribution must respect those rules and the project's contribution process. Ask whether the scope includes upstream submissions, who signs off on them, and how local-only terms will be kept separate from contributed ones.
What does your team need to provide for a localization project?
The work goes faster and costs less when your organization supplies a glossary, named reviewers and a staging environment. The glossary should cover product terms you want kept, such as your own brand names, and terms your analysts already use for metrics and dimensions. Reviewers need time in the review cycle and a native speaker of the target language who knows your business. Staging access lets the team test the build in the browser, check date and number formats against real data, and confirm that charts and reports still read correctly. Ask the partner to list these inputs in the written scope before work starts.
Can our own team do Superset localization in-house?
Yes, an internal team can do this if it has someone who can work with the Superset build process, a native speaker reviewer for each language, and a process for handling upgrades. The main risks are maintaining the glossary over time, keeping translations current after each upgrade, and testing formats across dashboards, alerts and reports. A partner is most useful for the first build, for enabling translation builds in your image, and for the upgrade test. Ask the team to estimate its own hours for each language and each release cycle, and compare that with a written scope from a partner before you decide.
What recurs after the first language goes live?
Recurring work includes translating new strings after each upgrade, reviewing terms that users report as unclear, keeping date and number formats correct, and rebuilding images when you change custom text. One-time work covers the initial glossary, the first translation pass, build changes and the first staging test. Ask for a quote that separates these two groups, names the languages and release versions covered, and states how many review rounds are included.
What changes for analysts, admins and developers after localization
Analysts will see a localized interface, but the data they read keeps its original form. Menus, buttons and chart labels that Superset renders from its translation files change language for anyone whose profile is set to that locale. The strings that programs read, such as SQL keywords and terms that tools depend on, stay in English, as the Superset translation guide explains, so analysts should expect a mix of translated labels and English identifiers. Dates, numbers and currency formats follow the locale setting and can differ from the language of the interface, so a German menu may still show a US-style decimal point in a table. Confirm with the analysts who will use the deployment which locale combinations they need, then test real dashboards with real data, including filters on date ranges and currency columns, before announcing the change.
Administrators own the per-user language and format decisions, and they need a rule for defaults. Each user can choose a language in their own settings, so administrators should decide which locales are enabled in the build, what the default is for new accounts, and how they will support users who switch languages unexpectedly. Role-based access is unaffected by localization, so the work is about consistency rather than permissions. Document which locale each team uses, check that exported files and scheduled reports carry the expected formats, and record the decision so that a later change to the default does not surprise a team that built its reports around the old one.
Developers carry the ongoing cost, because custom strings must stay aligned with upstream when Superset is upgraded. Any translated text added to a custom build, plugin or theme lives outside the upstream translation catalog, so it can drift from the English source strings after an upgrade. Plan a review step in each upgrade, following the steps in the upgrade documentation, that compares new and changed English strings with your overrides and retranslates any that changed. Ask your team to keep custom strings in one place, and treat missing or untranslated terms as a backlog item to contribute upstream where the change benefits other users, since the translation guide describes how contributions are made.
Where localization differs across deployment paths
If your team builds its own Superset image, the translation build is part of the image itself. Language files are compiled and packaged when the image is built, so a change to translations means a new image, a new tag and a rollout of that tag across every environment. Keep the translation source, the build arguments and the base version pinned together in your build pipeline so the same image can be rebuilt later and matched to the upgrade you tested.
- Build inputs: Record the Superset version, the translation changes and the build arguments in source control so a rebuild produces the same artifact.
- Promotion: Promote the identical image from staging to production rather than rebuilding it for each environment.
- Retest after upgrades: Check that every language still loads, that date and number formats render as expected and that login, dashboards and exports display translated labels.
- Dependencies: Rebuild when the base image or Python dependencies change, even if the translation files did not.
- Scanning: Rescan each new image after rebuilding, since translation changes alone do not remove the need for vulnerability review.
Before you build, confirm with the translation guide and the release documentation for your chosen version which build options and locales that version supports, and which strings are excluded from translation.
Installs from PyPI or from a source checkout let you apply translations at the Python environment or code level. The translation files travel with the installed package or the repository, so changes are made where the application code is installed, and the same upgrade rules apply. These paths give you the most direct control but leave the most room for drift between hosts, which matters when several web or worker nodes must show the same language.
- Consistency across nodes: Install the same package version and the same translation files on every web and worker node, and verify with a checksum or a configuration review.
- Source edits: If you patch translation files in a checkout, keep the patch in version control and reapply it during each upgrade, because upstream changes can conflict with local edits.
- Upgrade retests: After each version change, check the metadata database upgrade steps, then confirm translated pages, chart labels and error messages on every node.
- Virtual environments: Confirm that the locale data and translation files are present in the environment the web server actually uses, not only in a build directory.
- Contributions: If you want a missing term in upstream Superset, submit it through the project's contribution process rather than maintaining a long-lived local fork.
Before you change files, confirm with the vendor documentation for your version how translations are loaded and whether any build step is needed after installation.
On Kubernetes, translations usually arrive through the image referenced by the chart or the Operator, so the choice of deployment tool and the image source both matter. The official Helm chart is documented for the 6.1.0 release, but the current development documentation marks it as deprecated and points new deployments to the Apache Superset Kubernetes Operator, which is in alpha with a v1alpha1 API whose schemas may change between releases. Plan for either path to be tested against your own translated image before it reaches a cluster you rely on.
- Image reference: Point the chart or Operator at your own translated image by tag or digest, and avoid mutable tags for production.
- Helm chart status: Treat the deprecation notice as a planning input, and confirm whether your existing chart version will continue to receive changes.
- Operator risk: Because the Operator is alpha and its custom resource schema may change, pin its version and review release notes before each upgrade.
- Rolling restarts: Test that web pods and worker pods run the same image version during and after a rollout, so users do not see mixed languages.
- Retest scope: Recheck translated pages, scheduled reports and async query messages, since those run in worker components.
Before you choose a path, confirm with the Kubernetes installation documentation and the Operator documentation which tool and version your cluster will run, and what that tool's upgrade guidance says.
Contributing missing terms upstream to Apache Superset
Upstream contributions to Superset translations follow a sequence: find the gap, confirm the string is safe to translate, follow the project's guide, and submit for review. The project decides which terms are accepted, so plan for review time and keep local changes separate until then.
Identify missing or unclear terms
Start by listing the strings in your running Superset that show English where your users expect their language, or that translate to something confusing in context. Record the page, the role that sees it, and the exact source text. Unclear translations matter as much as missing ones, because a wrong term in a finance or admin screen can cause errors. Check the current translation files before you write anything, since the term may already exist under a slightly different string. Confirm with your language reviewers which wording your users actually use.
Check the do-not-translate list
Before proposing a change, check superset/translations/do-not-translate.txt in the repository. It lists strings that programs read, such as SQL keywords, and the translation guide says product names and terms users see in their own tools should stay in English. A string on that list must not be translated, even if it looks user-facing. If your term is a product name or a tool label, the correct contribution may be a note in your local documentation rather than a translation change.
Follow the translation guide
The translation guide in the Superset repository sets how strings are marked, extracted and compiled, and how language files are structured. Follow it exactly so your change applies to the right catalog and does not break the build. Test the compiled output in a local build and check that date, number and label formats still render correctly in the target language. Keep each change focused on one language and one set of related strings so reviewers can check it quickly.
Submit through the project's contribution process
Submit your change to the apache/superset repository using the project's pull request and contribution process. Describe the source string, the proposed translation, the context where users see it and the reason for the change. Expect questions from maintainers and native-speaking reviewers, and respond to them in the same thread. Acceptance is decided by the Apache Superset project and its maintainers, not by DeployOpen. We can prepare and submit a change on your behalf only where your organization authorizes it and the project's rules allow it.
Keep a local fork while review is pending
If upstream review takes longer than your rollout, keep your translated strings in a local fork or a patch set applied during your image build. Track each patch against the upstream pull request, so you can drop it once the project merges the same change. Each Superset upgrade may conflict with local translation patches, so rebase them as part of the upgrade test in staging. Document which strings differ from upstream so your team can explain the differences to users and reviewers.
