Skip to content

Latest commit

 

History

History
138 lines (100 loc) · 4.68 KB

Localize.md

File metadata and controls

138 lines (100 loc) · 4.68 KB

Localize

The Localize component emulates the ASP.NET Web Forms asp:Localize control. In Web Forms, Localize inherits directly from Literal and is functionally identical to it — the only difference is semantic. Localize marks text as localizable for design-time tooling and resource expression support (<%$ Resources:... %>). In Blazor, there is no design-time localization distinction, so this component exists purely for markup compatibility during migration.

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.localize?view=netframework-4.8

Features Supported in Blazor

  • Text - the text content to display (pass localized strings from IStringLocalizer<T>)
  • Mode - specifies how the content is rendered (Encode, PassThrough, or Transform)
  • Visible - controls whether the text is rendered

Blazor Notes

  • Localize inherits from Literal and behaves identically. All properties, rendering, and modes are inherited.
  • No wrapper HTML element is rendered — the text is output directly into the DOM.
  • When Mode is Encode (the default), text is HTML-encoded. When Mode is PassThrough, text is rendered as raw markup.

!!! warning "Localization in Blazor" In Web Forms, Localize enabled design-time localization via resource expressions like <%$ Resources:MyResource, MyKey %>. Blazor does not have resource expressions. Instead, inject IStringLocalizer<T> and pass localized strings to the Text property. See Microsoft's Blazor globalization documentation for details.

Web Forms Features NOT Supported

  • Resource Expressions (<%$ Resources:... %>) - Not supported in Blazor; use IStringLocalizer<T> instead
  • Design-time localization tooling - No Blazor equivalent; localization is handled at runtime via .NET localization APIs
  • EnableTheming / SkinID - Theming is not supported in Blazor

Web Forms Declarative Syntax

<asp:Localize
    EnableTheming="True|False"
    EnableViewState="True|False"
    ID="string"
    Mode="Transform|PassThrough|Encode"
    OnDataBinding="DataBinding event handler"
    OnDisposed="Disposed event handler"
    OnInit="Init event handler"
    OnLoad="Load event handler"
    OnPreRender="PreRender event handler"
    OnUnload="Unload event handler"
    runat="server"
    SkinID="string"
    Text="string"
    Visible="True|False"
/>

Blazor Syntax

Basic Usage

<Localize Text="Hello, World!" />

With Localized Text

@inject IStringLocalizer<MyPage> Localizer

<Localize Text="@Localizer["WelcomeMessage"]" />

With Mode

<Localize Text="<strong>Bold text</strong>" Mode="LiteralMode.PassThrough" />
<Localize Text="<script>alert('safe')</script>" Mode="LiteralMode.Encode" />

HTML Output

Localize renders no wrapper HTML element — text is output directly into the DOM, identical to Literal.

Blazor Input:

<Localize Text="Hello, World!" />

Rendered HTML:

Hello, World!

With Mode=PassThrough:

<Localize Text="<em>emphasized</em>" Mode="LiteralMode.PassThrough" />

Rendered HTML:

<em>emphasized</em>

With Mode=Encode (default):

<Localize Text="<em>encoded</em>" Mode="LiteralMode.Encode" />

Rendered HTML:

&lt;em&gt;encoded&lt;/em&gt;

Migration Notes

When migrating from Web Forms to Blazor:

  1. Remove asp: prefix - Change <asp:Localize> to <Localize>
  2. Remove runat="server" - Not needed in Blazor
  3. Replace resource expressions - Replace <%$ Resources:MyResource, MyKey %> with IStringLocalizer<T> injection
  4. Static text - If the Text was hardcoded, no additional changes are needed

Before (Web Forms)

<asp:Localize ID="lblWelcome"
              Text="<%$ Resources:Messages, WelcomeText %>"
              Mode="Encode"
              runat="server" />

After (Blazor)

@inject IStringLocalizer<MyPage> Localizer

<Localize Text="@Localizer["WelcomeText"]" Mode="LiteralMode.Encode" />

!!! tip "Consider Using Literal" Since Localize is identical to Literal in Blazor, you can use either component interchangeably. If you are writing new Blazor code (not migrating), Literal is the conventional choice. Use Localize when migrating existing markup that already uses <asp:Localize> to minimize changes.

See Also