This is an automated email from the ASF dual-hosted git repository. rusackas pushed a commit to branch docs/build-translations-custom-image in repository https://gitbox.apache.org/repos/asf/superset.git
commit 169c1c1117a244de28b7f894513f30db8d1f8995 Author: rusackas <[email protected]> AuthorDate: Wed Jul 29 15:55:48 2026 -0700 docs(installation): document how to add translations to a custom Docker image BUILD_TRANSLATIONS only takes effect when building the image from source; extending an already-published tag in a small downstream Dockerfile (the pattern already documented on this page) can't add translations after the fact, since non-English files are already stripped out of the published layers. That distinction wasn't documented anywhere, and came up repeatedly in #35959 as real user confusion after 5.0.0 made translations opt-in. Documents the working multi-stage COPY --from pattern a community member worked out in that issue for pulling the compiled translation files out of the superset-node/python-translation-compiler build stages, and clarifies the BUILD_TRANSLATIONS ARG description to point at it. --- docs/admin_docs/installation/docker-builds.mdx | 46 ++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/docs/admin_docs/installation/docker-builds.mdx b/docs/admin_docs/installation/docker-builds.mdx index ffd523b906d..5bf3e4b568f 100644 --- a/docs/admin_docs/installation/docker-builds.mdx +++ b/docs/admin_docs/installation/docker-builds.mdx @@ -112,12 +112,54 @@ USER superset CMD ["/app/docker/entrypoints/run-server.sh"] ``` +### Adding translations to a custom image + +The pattern above, a small Dockerfile that just extends `FROM apache/superset:...`, can't add +translations after the fact. By the time an official tag is published, its frontend and backend +layers have already had non-English translation files stripped out unless `BUILD_TRANSLATIONS` +was set at build time (see below), and there's no `superset/translations` source tree left in the +final image to compile from. + +To get translations into your own image, you need to build from the full Superset source (a +clone or fork of this repo) rather than extend a published tag. The most efficient way to do this +is to append your customizations as one more stage at the end of the repo's own `Dockerfile`, so +Docker can reuse the cached upstream layers and only rebuild what your stage adds: + +```Dockerfile +# Append this to the end of the repo's Dockerfile +FROM apache/superset:5.0.0 AS my-custom-image +USER root + +# Pull the compiled translation files out of the earlier build stages. These +# only exist mid-build (frontend .json in `superset-node`, backend .mo in +# `python-translation-compiler`) and get stripped from the final `lean`/`dev` +# stages unless BUILD_TRANSLATIONS=true. +COPY --from=superset-node /app/superset/translations superset/translations +COPY --from=python-translation-compiler /app/translations_mo superset/translations + +USER superset +``` + +Then build with: + +```bash +docker build --target=my-custom-image --build-arg=BUILD_TRANSLATIONS=true -t mysuperset:5.0.0 . +``` + +You can combine this with the database-driver/dependency pattern above by adding your own +`RUN uv pip install ...` step before switching back to `USER superset`. See +[issue #35959](https://github.com/apache/superset/issues/35959) for the discussion this pattern +came out of, credit to the community for working it out. + ## Key ARGs in Dockerfile - `BUILD_TRANSLATIONS`: whether to build the translations into the image. For the frontend build this tells webpack to strip out all locales other than `en` from - the `moment-timezone` library. For the backendthis skips compiling the - `*.po` translation files + the `moment-timezone` library. For the backend this skips compiling the + `*.po` translation files. This only takes effect when building the image from source + (`docker build` against this repo's own `Dockerfile`); it has no effect on a downstream + Dockerfile that just extends an already-published tag, see + "Adding translations to a custom image" above. - `DEV_MODE`: whether to skip the frontend build, this is used by our `docker-compose` dev setup where we mount the local volume and build using `webpack` in `--watch` mode, meaning as you alter the code in the local file system, webpack, from within a docker image used for this
