Skip to main content

Quickstart

This guide gets Translazor running in a Blazor Server app in a few minutes.

Index​

Privacy note​

Translazor does not store your translated content on Translazor servers. Your Azure Translator key stays inside your application. See Privacy & Data for more details.

Requirements​

Before you start, make sure your app uses:

  • .NET 8 or later
  • Blazor Server
  • An Azure Translator key and region
  • Optional: Redis, if you want shared or persistent distributed caching

Translazor currently targets Blazor Server. Blazor WebAssembly support is planned for the future.

1. Install NuGet​

Install the Translazor package:

dotnet add package Translazor

Or using the NuGet Package Manager Console:

Install-Package Translazor

2. Configure appsettings.json​

Add a Translazor section to your appsettings.json.

{
  "Translazor": {
    "Translation": {
      "AutoDetectSourceLanguage": false,
      "DefaultSourceLanguage": "en",
      "ThrowIfUnsupportedLanguage": true,
      "FallbackLanguage": "en",
      "SupportedLanguages": [ "de", "fr" ]
    },
    "AzureSettings": {
      "ApiKey": "YOUR_AZURE_TRANSLATOR_KEY",
      "AzureRegion": "YOUR_AZURE_TRANSLATOR_REGION"
    },
    "Redis": {
      "Host": "localhost",
      "Port": 6379,
      "User": "",
      "Password": ""
    },
    "Cache": {
      "ExpirationInDays": 30
    }
  }
}

For local development, MemoryCache is usually enough.

For production apps running on multiple servers or containers, Redis is recommended.

3. Register Translazor in Program.cs​

Open Program.cs and register Translazor services.

using Translazor.ServicesRegisteration;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

builder.Services.AddBlazorTranslation(options =>
{
    options.UseConfiguration(builder.Configuration);
    options.CacheSectionName = "MyCacheSettings";
    options.UseMemoryCache();
});

var app = builder.Build();

app.UseStaticFiles();
app.UseAntiforgery();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.Run();

Check the configuration page if you are using advanced options.

4. Enable Interactive Server Rendering​

For Translazor to update visible page content and SEO metadata after translations are loaded, your Blazor app should use interactive server rendering.

In App.razor, make sure HeadOutlet and Routes are interactive:

<!DOCTYPE html>
<html lang="en">
<head>
    <HeadOutlet @rendermode="InteractiveServer" />
</head>
<body>
    <Routes @rendermode="InteractiveServer" />
</body>
</html>

Without interactive rendering, static content may render, but dynamic translation updates may not refresh correctly.

5. Add Language Switching​

Add the LanguageSelector component somewhere visible, such as your layout or navigation menu.

<LanguageSelector />

You can also choose how languages are displayed:

<LanguageSelector DisplayMode="LanguageDisplayMode.Name" />

Or:

<LanguageSelector DisplayMode="LanguageDisplayMode.Code" />

Translazor can initialize the current language from a dropdown selection or from the URL, depending on your configuration.

Example URL-based language routing:

/en/home
/lt/home
/ar/home

For more details, see the Language Switching guide.

6. Translate Page Content​

Use TranslatableText for content that should be translated.

<TranslatableText Key="home.hero.title"
                  Fallback="Translate your Blazor Server app at runtime." />

<TranslatableText Key="home.hero.subtitle"
                  Fallback="Translazor helps you translate page content, SEO metadata, and user-facing text using Azure Translator and caching." />

The Key is used to identify the text in the translation cache.

The Fallback is the original text shown before a translation is available, or when the selected language is the default language.

7. Translate SEO Metadata​

Use TranslatedHead to translate page titles and metadata.

<TranslatedHead TitleKey ="home.meta.title"
                Title ="Translazor - Runtime Translation for Blazor Server"
                MetaDescriptionKey="home.meta.description"
                MetaDescription="Translate Blazor Server apps at runtime with Azure Translator, caching, SEO metadata translation, and admin overrides." />

You can also translate social metadata such as Open Graph and Twitter/X tags.

<TranslatedHead TitleKey ="home.meta.title"
                Title ="Translazor - Runtime Translation for Blazor Server"
                MetaDescriptionKey ="home.meta.description"
                MetaDescription ="Translate Blazor Server apps at runtime with Azure Translator and caching."
                OgTitleKey="home.og.title"
                OgTitleFallback="Translazor for Blazor Server"
                OgDescriptionKey="home.og.description"
                OgDescriptionFallback="Runtime translation, caching, SEO metadata, and admin overrides for Blazor Server apps." />

For a deeper explanation, see the Translating Head and SEO Metadata guide.

Next Steps​

After completing the quickstart, you can continue with:

  • Configuration — learn all available settings.
  • Azure Translator and Redis — understand required third-party services.
  • Language Switching — configure dropdown or URL-based language selection.
  • Translating Page Content — translate visible UI text.
  • Translating Head and SEO Metadata — translate titles, meta descriptions, and social tags.
  • Caching — choose between MemoryCache and Redis.
  • Admin Panel — review and override generated translations.