How to create a multi-language website with internationalization (i18n)?

[MicaelJarniac]

First Check

• I added a very descriptive title here.
• I have checked the FAQs for a similar question and didn't find it.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the NiceGUI documentation, with the integrated search.
• I already searched online "How to X in NiceGUI" and didn't find any information.

Example Code

N/A

Description

I'd like to know what's the best way of creating a multi-lang website with proper internationalization (i18n).

I believe it'd be nice having an official example for this, as well as perhaps better API support.

Wishlist:

• detect user's language automatically
• offer manual override
• change language of text on the page
• change language of built-in elements

Some related discussions:

• Allow changing the language dynamically #4295
• Request for an example of a multilingual application #4511
• Retrieving the Navigator Language #2771
• Internationalization (i18n) for NiceGUI #389

Sorry if this discussion is a duplicate, but it took a while to find all the pieces I have so far, and I think it'd be worth to at least centralize this information so it's easier for others to find.

I'll see what I can piece together with what's available.

NiceGUI Version

3.8.0

Python Version

Python 3.14.3

Browser

Chrome

Operating System

macOS

Additional Context

No response

[evnchn]

Hello @MicaelJarniac

You have missed #5825 by yours truly 😭

It may not be the best approach, but it's a decent one.

I have thought about adding i18n-awareness to NiceGUI elements, but I guess that will only happen after #5825 receives the attention which it fully deserves.

[MicaelJarniac]

Oh, nice. I did miss it indeed. I 👍ed it now, tho. Thanks!

[falkoschindler]

Let me quickly share how we did a bilingual translation system for our company website.

We built zauberzeug.com with NiceGUI and have a working German/English i18n setup. It's intentionally simple — no framework, no .po files, just plain Python. Here's how it works:

Language detection & storage

A small Language class wraps app.storage.user. On every page load we call language.set(''), which:

1. Returns immediately if a preference is already stored
2. Otherwise parses the browser's Accept-Language header for de or en
3. Falls back to English

class Language:
    @property
    def current(self) -> str:
        return app.storage.user.get('language', 'en')

    @current.setter
    def current(self, code: str) -> None:
        if code == '':
            if 'language' in app.storage.user:
                return
            if ui.context.client.request:
                for lang in ui.context.client.request.headers.get('accept-language', '').split(','):
                    if lang[:2] in ('de', 'en'):
                        code = lang[:2]
                        break
        app.storage.user['language'] = code or 'en'

    @property
    def is_de(self) -> bool:
        return self.current == 'de'

Manual override

A toggle button in the header calls language.switch(), which flips the stored value and does a full page reload:

def switch(self) -> None:
    self.set('en' if self.is_de else 'de')
    ui.navigate.reload()

We deliberately chose a hard reload over reactive bindings — it keeps things simple and ensures every component re-renders with consistent language.

Translation pattern

Our reusable components accept _de / _en pairs and pick the right one at render time:

class tile(ui.column):
    def __init__(self, *, title_de: str, title_en: str, text_de: str, text_en: str, ...):
        ...
        ui.label(title_de if language.is_de else title_en)

For one-off text we just use inline ternaries:

ui.page_title('Produkte' if language.is_de else 'Products')

What we don't do

• No language prefix in URLs (/de/..., /en/...) — language is purely client-side via app.storage.user
• No translation files — with only two languages and a moderate amount of content, inline strings keep things local and easy to review
• No reactive bindings for language — the page reload is simpler and avoids stale translations

This approach won't scale to 10+ languages or hundreds of translated strings, but for a bilingual company website it's been working well.

[evnchn]

Totally sounds like what @falkoschindler would do. Simplicity is key.

However, I must set the scene straight: It does not work well SEO-sense since "language is purely client-side via app.storage.user" means "Googlebot can't use it whatsoever"

Doing search on Zauberzeug on German VPN still yields English description text...

[MicaelJarniac]

I managed to add i18n to my web app, here's the PR if anyone is interested:

• feat: add i18n support with gettext MicaelJarniac/ogdrb#12

I'm using Python's own gettext module + Babel + Nox (for automating).

[manimovassagh]

Adding another approach here for anyone looking at i18n in NiceGUI — using Python's built-in gettext with a lightweight wrapper that plays nicely with NiceGUI's per-client architecture.

Setup with gettext + per-user locale

import gettext
from pathlib import Path
from nicegui import app, ui

LOCALES_DIR = Path(__file__).parent / "locales"
SUPPORTED = ("en", "de", "es", "fr")

def get_translator():
    """Get a translation function for the current user's locale."""
    lang = app.storage.user.get("language", "en")
    try:
        t = gettext.translation("messages", LOCALES_DIR, languages=[lang])
    except FileNotFoundError:
        t = gettext.NullTranslations()
    return t.gettext

@ui.page("/")
def index():
    _ = get_translator()

    with ui.header():
        ui.label(_("Welcome"))
        for lang in SUPPORTED:
            ui.button(lang.upper(), on_click=lambda l=lang: set_language(l)).props("flat dense")

    ui.label(_("This is the home page"))

def set_language(lang: str):
    app.storage.user["language"] = lang
    ui.navigate.reload()

ui.run(storage_secret="your-secret")

Generate locale files with Babel:

# Extract strings
pybabel extract -F babel.cfg -o messages.pot .

# Create locale
pybabel init -i messages.pot -d locales -l de

# After translating locales/de/LC_MESSAGES/messages.po:
pybabel compile -d locales

The babel.cfg file:

[python: **.py]
encoding = utf-8

Auto-detect browser language:

@ui.page("/")
def index():
    if "language" not in app.storage.user:
        request = ui.context.client.request
        accept = request.headers.get("accept-language", "en")
        detected = accept.split(",")[0][:2]
        app.storage.user["language"] = detected if detected in SUPPORTED else "en"

    _ = get_translator()
    # ... rest of page

This scales to any number of languages, uses standard .po files that translators already know, and keeps each user's preference isolated via app.storage.user. The reload-on-switch approach (as the zauberzeug team described above) is the right call — simpler than trying to reactively update every label.