You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@superset.apache.org by ru...@apache.org on 2026/09/04 20:41:10 UTC

(superset) branch docs/pr-41780-needs-docs-feat-i18n-serve-language-pack created (now 146043e7072)

This is an automated email from the ASF dual-hosted git repository.

rusackas pushed a change to branch docs/pr-41780-needs-docs-feat-i18n-serve-language-pack
in repository https://gitbox.apache.org/repos/asf/superset.git


      at 146043e7072 docs(i18n): document versioned language pack script delivery

This branch includes the following new commits:

     new 146043e7072 docs(i18n): document versioned language pack script delivery

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.



(superset) 01/01: docs(i18n): document versioned language pack script delivery

Posted by ru...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

rusackas pushed a commit to branch docs/pr-41780-needs-docs-feat-i18n-serve-language-pack
in repository https://gitbox.apache.org/repos/asf/superset.git

commit 146043e7072c5d15096fe4c971588feb3009c1af
Author: rusackas <ev...@rusackas.com>
AuthorDate: Fri Sep 4 13:40:51 2026 -0700

    docs(i18n): document versioned language pack script delivery
    
    #41780 made spa.html load the frontend translation catalog as a
    separate, content-addressed, cacheable script instead of inlining it
    into the HTML, but didn't add operator-facing docs explaining the
    caching behavior or how it interacts with COMMON_BOOTSTRAP_OVERRIDES_FUNC.
    
    Co-Authored-By: Claude <no...@anthropic.com>
---
 .../configuration/configuring-superset.mdx         | 35 ++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/docs/admin_docs/configuration/configuring-superset.mdx b/docs/admin_docs/configuration/configuring-superset.mdx
index f30cdaedc7c..59520b64898 100644
--- a/docs/admin_docs/configuration/configuring-superset.mdx
+++ b/docs/admin_docs/configuration/configuring-superset.mdx
@@ -145,6 +145,41 @@ D3_TIME_FORMAT = {
 Restart Superset after changing `superset_config.py` so the frontend receives
 the updated formatter configuration.
 
+## Serving translated language packs
+
+Non-English page loads need the frontend translation catalog (the "language
+pack") available before the entry bundle runs, so translations are in place
+for the very first render instead of racing a later fetch. Superset delivers
+that pack as a separate, cacheable script rather than inlining it into the
+HTML:
+
+```html
+<script src="/language_pack/pt_BR/1a2b3c4d5e6f/script.js"></script>
+```
+
+`spa.html` emits this tag, pointing at the `language_pack_script` view, before
+loading the entry bundle whenever the request's locale isn't English. The
+`<version>` segment is a short hash of the pack's contents, so the URL is
+content-addressed:
+
+- When the version in the URL matches the server's current pack, the response
+  carries `Cache-Control: public, max-age=31536000, immutable` — the browser
+  fetches that language's pack once and reuses it across sessions.
+- If a cached HTML page references a version that's since changed (e.g. after
+  a translation update or upgrade), the endpoint still serves the current
+  pack, but with `Cache-Control: no-cache` so that response isn't cached under
+  the now-stale URL.
+- English pages emit no script tag; there's no pack to load.
+
+This endpoint is intentionally unauthenticated. Translation catalogs are
+static, public content shipped in the Superset repo, and the login page and
+embedded dashboards need them to load before a user session exists.
+
+If you already override the language pack via `COMMON_BOOTSTRAP_OVERRIDES_FUNC`
+(a `common.language_pack` value, historically used to work around translation
+race conditions), that override still takes precedence: `spa.html` skips the
+script tag and uses your supplied pack instead.
+
 ## Chart-data query timing
 
 Set `CHART_DATA_INCLUDE_TIMING = True` to add an optional versioned timing object