Language Switching

Translazor supports different ways to choose the current language in a Blazor Server app.

The right setup depends on how you want language switching to behave in your application.

Quick decision

Use case	Recommended setup	URL changes?	Best for
Public website / SEO	`LanguageInitMode.FromUrl`	Yes	Landing pages, blogs, documentation, marketing websites
Public website with a dropdown	`LanguageInitMode.FromUrl` + `LanguageNavigationSelector`	Yes	Public sites that need a language switcher
Dashboard / admin app	`LanguageSelector`	No	Interactive Blazor Server apps, dashboards, admin panels

Recommended starting point:

Use LanguageInitMode.FromUrl for public websites.
Use LanguageNavigationSelector if you want a dropdown that navigates users to language-specific URLs.
Use LanguageSelector for dashboards or admin panels where changing the URL is not important.

For most public websites, we recommend URL-based language detection using LanguageInitMode.FromUrl. This gives translated pages their own URLs, which is usually better for users, sharing, and SEO.

For dashboards and internal applications, in-page switching is usually enough because SEO is normally not important there.

How Translazor chooses the current language

Translazor can initialize the current language in two main ways:

From the URL, using LanguageInitMode.FromUrl
From an in-page selector, using LanguageSelector

When you use LanguageInitMode.FromUrl, Translazor reads the language from the current URL according to your application routing and navigation setup.

For example, your website may use URLs like:

/about/ar
/about/fr
/about/lt

Or you may prefer URLs like:

/ar/about
/fr/about
/lt/about

The URL style is part of your application's routing strategy. Use the pattern that fits your website structure and keep your generated links consistent with it.

URL-based language detection is useful when:

users open direct translated links
users share translated pages
search engines crawl translated pages
your sitemap contains language-specific URLs
you want public pages to have separate URLs per language

You do not have to use a dropdown with this approach. If the user opens a language-specific URL directly, Translazor can load the matching translation automatically.

Configure `BlazorTranslator` for URL-based language detection

To enable URL-based language detection, wrap your Blazor Router with BlazorTranslator and set Mode to LanguageInitMode.FromUrl.

Example:

<BlazorTranslator Mode="LanguageInitMode.FromUrl" UpdatePageDirection="false">
    <Router AppAssembly="typeof(Program).Assembly">
        <Found Context="routeData">
            <RouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
            <FocusOnNavigate RouteData="routeData" Selector="h1" />
        </Found>
    </Router>
</BlazorTranslator>

With this setup, Translazor initializes the selected language from the URL and loads the matching translations.

For example, your application can use language-specific URLs such as:

/about/ar
/about/fr
/about/lt

or:

/ar/about
/fr/about
/lt/about

Choose one URL style for your website and use it consistently in your links, menus, sitemap, and language switcher.

URL patterns

Translazor can be used with different URL patterns depending on how your Blazor routes and navigation are designed.

Common examples include:

/about/ar

and:

/ar/about

The important part is consistency.

If your website generates links using one pattern, your routing and language navigation should follow the same pattern.

For example, avoid mixing these styles randomly:

/about/ar
/fr/about
/contact/lt

Unless you intentionally support multiple patterns, keep one clear URL strategy across the website.

How Translazor refreshes translated content

Translazor can update:

visible page content
navigation text
placeholders and other translated UI text
optionally <title> and <meta> tags inside <head>

To allow Blazor to refresh translated UI content after translations are loaded, the parts of the app that display translated content must be rendered in InteractiveServer mode.

If you only translate visible page content, Routes is usually the most important part.

If you also translate page title or meta description, HeadOutlet must be interactive too.

In a fully interactive Blazor Server app, this usually means:

<HeadOutlet @rendermode="InteractiveServer" />
<Routes @rendermode="InteractiveServer" />

However, not every website needs the entire app to be interactive. The right setup depends on your use case.

Option A: Simple setup for fully interactive apps

Use this setup if your whole Blazor Server app is already interactive.

This is common for:

dashboards
admin panels
internal business apps
apps where users are already connected to the server most of the time

In App.razor, render both HeadOutlet and Routes as InteractiveServer:

<!DOCTYPE html>
<html lang="en">
<head>
    ...
    <HeadOutlet @rendermode="InteractiveServer" />
</head>
<body>
    <Routes @rendermode="InteractiveServer" />
    <script src="_framework/blazor.web.js"></script>
</body>
</html>

This is the easiest setup and works well for apps where interactivity is expected on most pages.

Option B: Mixed setup for public websites

Use this setup if your website has both:

static public pages
translated pages that need interactive refresh

This approach is useful when you want to keep most pages static, but enable InteractiveServer only for translated language routes.

For example, you may want language-specific pages to be interactive, while default pages stay static.

<!DOCTYPE html>
<html lang="en">
<head>
    ...
    <HeadOutlet @rendermode="@CurrentRenderMode" />
</head>
<body>
    <Routes @rendermode="@CurrentRenderMode" />
    <script src="_framework/blazor.web.js"></script>
</body>
</html>

@code {
    [CascadingParameter]
    public HttpContext HttpContext { get; set; } = default!;

    private static readonly string[] SupportedLanguageSegments =
    [
        "ar",
        "lt",
        "fr",
        "de"
    ];

    private IComponentRenderMode? CurrentRenderMode
        => IsTranslatedRequest()
            ? InteractiveServer
            : null;

    private bool IsTranslatedRequest()
    {
        var path = HttpContext.Request.Path.Value ?? "";

        return SupportedLanguageSegments.Any(language =>
            path.Equals($"/{language}", StringComparison.OrdinalIgnoreCase) ||
            path.StartsWith($"/{language}/", StringComparison.OrdinalIgnoreCase) ||
            path.EndsWith($"/{language}", StringComparison.OrdinalIgnoreCase) ||
            path.Contains($"/{language}/", StringComparison.OrdinalIgnoreCase));
    }
}

In this example, the app enables InteractiveServer when the current URL contains one of the supported language segments.

You can adjust this logic based on your own routing strategy.

For example, if your website only supports language prefixes such as /ar/about, you can simplify the check to match only prefix-style URLs.

If your website only supports language suffixes such as /about/ar, you can simplify the check to match only suffix-style URLs.

Language switcher components

Translazor provides two language switcher components:

LanguageSelector
LanguageNavigationSelector

You do not have to use a switcher component if you already have your own links, menu, sitemap, or language-specific URLs.

In that case, use LanguageInitMode.FromUrl and navigate users directly to your translated URLs.

`LanguageSelector`

Use LanguageSelector when you want to change the language without changing the URL.

Example:

<LanguageSelector DisplayMode="LanguageDisplayMode.Name" />

This is best for:

dashboards
admin panels
authenticated apps
apps where SEO is not important
apps where you do not need language-specific URLs

Because this component updates the current page directly, your Routes component must be interactive:

<Routes @rendermode="InteractiveServer" />

If you also translate <title> or <meta> tags, make HeadOutlet interactive too:

<HeadOutlet @rendermode="InteractiveServer" />

Example usage inside a navigation menu:

@using Translazor.Components
@using Translazor.Enums

<div class="nav-scrollable" onclick="document.querySelector('.navbar-toggler').click()">
    <nav class="nav flex-column">
        <div class="nav-item px-3">
            <LanguageSelector DisplayMode="LanguageDisplayMode.Name" />
        </div>

        <div class="nav-item px-3">
            <NavLink class="nav-link" href="" Match="NavLinkMatch.All">
                <span class="bi bi-house-door-fill-nav-menu" aria-hidden="true"></span>
                <TranslatableText Key="Nav.Home" Text="Home" />
            </NavLink>
        </div>

        <div class="nav-item px-3">
            <NavLink class="nav-link" href="counter">
                <span class="bi bi-plus-square-fill-nav-menu" aria-hidden="true"></span>
                <TranslatableText Key="Nav.Counter" Text="Counter" />
            </NavLink>
        </div>

        <div class="nav-item px-3">
            <NavLink class="nav-link" href="weather">
                <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span>
                <TranslatableText Key="Nav.Weather" Text="Weather" />
            </NavLink>
        </div>
    </nav>
</div>

`LanguageNavigationSelector`

Use LanguageNavigationSelector when you want the user to switch language by navigating to a language-specific URL.

Example:

<LanguageNavigationSelector DisplayMode="LanguageDisplayMode.Name" @rendermode="InteractiveServer" />

For example, if the user selects Arabic on the About page, your application can navigate to a language-specific URL such as:

/about/ar

or:

/ar/about

depending on your routing strategy.

This is best for:

public websites
SEO-friendly pages
landing pages
blogs
documentation
websites where each language should have its own URL

With this approach, the whole Routes component does not always need to be interactive. The language selector itself can be interactive, while the page is loaded through its language-specific URL.

Example usage inside a navigation menu:

@using Translazor.Components
@using Translazor.Enums

<div class="nav-scrollable" onclick="document.querySelector('.navbar-toggler').click()">
    <nav class="nav flex-column">
        <div class="nav-item px-3">
            <LanguageNavigationSelector DisplayMode="LanguageDisplayMode.Name" @rendermode="InteractiveServer" />
        </div>

        <div class="nav-item px-3">
            <NavLink class="nav-link" href="" Match="NavLinkMatch.All">
                <span class="bi bi-house-door-fill-nav-menu" aria-hidden="true"></span>
                <TranslatableText Key="Nav.Home" Text="Home" />
            </NavLink>
        </div>

        <div class="nav-item px-3">
            <NavLink class="nav-link" href="counter">
                <span class="bi bi-plus-square-fill-nav-menu" aria-hidden="true"></span>
                <TranslatableText Key="Nav.Counter" Text="Counter" />
            </NavLink>
        </div>

        <div class="nav-item px-3">
            <NavLink class="nav-link" href="weather">
                <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span>
                <TranslatableText Key="Nav.Weather" Text="Weather" />
            </NavLink>
        </div>
    </nav>
</div>

You can also use URL-based switching without showing any Translazor language selector component.

In this case, use LanguageInitMode.FromUrl:

<BlazorTranslator Mode="LanguageInitMode.FromUrl" UpdatePageDirection="false">
    <Router AppAssembly="typeof(Program).Assembly">
        <Found Context="routeData">
            <RouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
            <FocusOnNavigate RouteData="routeData" Selector="h1" />
        </Found>
    </Router>
</BlazorTranslator>

Then create normal links to translated pages:

<a href="/about/ar">Arabic</a>
<a href="/about/fr">French</a>
<a href="/about/lt">Lithuanian</a>

Or, if your website uses language prefixes:

<a href="/ar/about">Arabic</a>
<a href="/fr/about">French</a>
<a href="/lt/about">Lithuanian</a>

When the user opens a language-specific URL, Translazor initializes the language from the URL and loads the matching translation.

This approach is best when you want full control over your own navigation UI, or when translated links are generated by your website menu, sitemap, documentation, or SEO pages.

Avoid mixing selector types

Avoid using LanguageSelector and LanguageNavigationSelector on the same page unless you have a specific reason.

They solve different problems:

LanguageSelector changes the language inside the current page.
LanguageNavigationSelector changes the URL and navigates to a language-specific page.

For public websites, prefer URL-based navigation.

For dashboards and admin panels, in-page switching is usually enough.

Which one should you use?

Use LanguageInitMode.FromUrl for public websites where each language should have its own URL.

Use LanguageNavigationSelector if you also want to provide a ready-made dropdown that navigates users to translated URLs.

Use LanguageSelector for interactive apps where changing the language without changing the URL is enough.

If you are not sure, start with:

LanguageInitMode.FromUrl for websites
LanguageSelector for dashboards

Quick decision​

How Translazor chooses the current language​

Configure BlazorTranslator for URL-based language detection​

URL patterns​

How Translazor refreshes translated content​

Option A: Simple setup for fully interactive apps​

Option B: Mixed setup for public websites​

Language switcher components​

LanguageSelector​

LanguageNavigationSelector​

URL-based switching without a dropdown​

Avoid mixing selector types​

Which one should you use?​

Quick decision

How Translazor chooses the current language

Configure `BlazorTranslator` for URL-based language detection

URL patterns

How Translazor refreshes translated content

Option A: Simple setup for fully interactive apps

Option B: Mixed setup for public websites

Language switcher components

`LanguageSelector`

`LanguageNavigationSelector`

URL-based switching without a dropdown

Avoid mixing selector types

Which one should you use?