Globalización y localización de Blazor de ASP.NET Core

Establezca la propiedad BlazorWebAssemblyLoadAllGlobalizationData en true en el archivo del proyecto de la aplicación (.csproj):

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Las aplicaciones Blazor Server se localizan usando un middleware de localización. Agregue servicios de localización a la aplicación con AddLocalization.

En Program.cs:

builder.Services.AddLocalization();

Especifique las referencia culturales admitidas de la aplicación en Program.cs inmediatamente después de agregar el middleware de enrutamiento a la canalización de procesamiento. En el ejemplo siguiente se configuran las referencia culturales admitidas para inglés de Estados Unidos y español de Chile:

app.UseRequestLocalization(new RequestLocalizationOptions()
    .AddSupportedCultures(new[] { "en-US", "es-CL" })
    .AddSupportedUICultures(new[] { "en-US", "es-CL" }));

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Program.cs, vea Middleware de ASP.NET Core.

Establezca la propiedad BlazorWebAssemblyLoadAllGlobalizationData en true en el archivo del proyecto de la aplicación (.csproj):

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

La referencia cultural de la aplicación se puede establecer en JavaScript cuando Blazor comienza con la opción de inicio applicationCulture de Blazor. En el ejemplo siguiente se configura la aplicación para que se inicie con la referencia cultural de inglés de Estados Unidos (en-US).

• En wwwroot/index.html, evite el inicio automático de Blazor agregando autostart="false" a la etiqueta <script> de Blazor:

  <script src="_framework/blazor.webassembly.js" autostart="false"></script>
  

• Agregue el siguiente bloque <script> después de la etiqueta <script> de Blazor y antes de la etiqueta </body> de cierre:

  <script>
    Blazor.start({
      applicationCulture: 'en-US'
    });
  </script>
  

El valor de applicationCulture debe ajustarse al formato de etiqueta de idioma BCP-47. Para más información sobre el inicio de Blazor, vea Inicio de Blazor en ASP.NET Core.

Una alternativa a establecer la opción de inicio Blazor de la referencia cultural es definir la referencia cultural en código de C#. Establezca CultureInfo.DefaultThreadCurrentCulture y CultureInfo.DefaultThreadCurrentUICulture en Program.cs.

Agregue el espacio de nombres System.Globalization a Program.cs:

using System.Globalization;

Agregue la configuración de la referencia cultural antes de la línea que compila y ejecuta WebAssemblyHostBuilder (await builder.Build().RunAsync();):

CultureInfo.DefaultThreadCurrentCulture = new CultureInfo("en-US");
CultureInfo.DefaultThreadCurrentUICulture = new CultureInfo("en-US");

Las aplicaciones Blazor Server se localizan usando un middleware de localización. Agregue servicios de localización a la aplicación con AddLocalization.

En Program.cs:

builder.Services.AddLocalization();

Especifique la referencia cultural estática en Program.cs inmediatamente después de agregar el middleware de enrutamiento a la canalización de procesamiento. En el ejemplo siguiente se configura inglés de Estados Unidos:

app.UseRequestLocalization("en-US");

El valor de la referencia cultural de UseRequestLocalization debe ajustarse al formato de etiqueta de idioma BCP-47.

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Program.cs, vea Middleware de ASP.NET Core.

Entre los ejemplos de ubicaciones en las que una aplicación podría almacenar las preferencias de un usuario se incluyen el almacenamiento local del explorador (común en las aplicaciones Blazor WebAssembly), en una localización cookie o base de datos (común en las aplicaciones de Blazor Server) o en un servicio externo asociado a una base de datos externa y al que tiene acceso una API web. En el ejemplo siguiente se muestra cómo usar el almacenamiento local del explorador.

Agregue la referencia del proyecto del paquete Microsoft.Extensions.Localization al archivo del proyecto de la aplicación (.csproj):

<PackageReference Include="Microsoft.Extensions.Localization" Version="{VERSION}" />

El marcador de posición {VERSION} de la referencia del paquete anterior es la versión del paquete.

Establezca la propiedad BlazorWebAssemblyLoadAllGlobalizationData en true en el archivo del proyecto:

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

La referencia cultural de la aplicación en una aplicación Blazor WebAssembly se establece mediante la API del marco de Blazor. La selección de la referencia cultural de un usuario se puede conservar en el almacenamiento local del explorador.

En el archivo wwwroot/index.html después de la etiqueta <script> de Blazor y antes de la etiqueta de cierre </body>, proporcione funciones de JS para obtener y establecer la selección de la referencia cultural del usuario con el almacenamiento local del explorador:

<script>
  window.blazorCulture = {
    get: () => window.localStorage['BlazorCulture'],
    set: (value) => window.localStorage['BlazorCulture'] = value
  };
</script>

export function getBlazorCulture() {
  return window.localStorage['BlazorCulture'];
};
export function setBlazorCulture(value) {
  window.localStorage['BlazorCulture'] = value;
};

Agregue los espacios de nombres para System.Globalization y Microsoft.JSInterop en la parte superior de Program.cs:

using System.Globalization;
using Microsoft.JSInterop;

Quite las siguientes líneas de Program.cs:

- await builder.Build().RunAsync();

Reemplace la línea anterior por el código siguiente. El código agrega el servicio de localización de Blazor a la colección de servicios de la aplicación con AddLocalization y usa la interoperabilidad de JS para llamar a JS y recuperar la selección de referencia cultural del usuario del almacenamiento local. Si el almacenamiento local no contiene ninguna referencia cultural para el usuario, el código establece un valor predeterminado de inglés de Estados Unidos (en-US).

builder.Services.AddLocalization();

var host = builder.Build();

CultureInfo culture;
var js = host.Services.GetRequiredService<IJSRuntime>();
var result = await js.InvokeAsync<string>("blazorCulture.get");

if (result != null)
{
    culture = new CultureInfo(result);
}
else
{
    culture = new CultureInfo("en-US");
    await js.InvokeVoidAsync("blazorCulture.set", "en-US");
}

CultureInfo.DefaultThreadCurrentCulture = culture;
CultureInfo.DefaultThreadCurrentUICulture = culture;

await host.RunAsync();

El componente CultureSelector siguiente muestra cómo establecer la selección de referencia cultural del usuario en el almacenamiento local del explorador mediante la interoperabilidad de JS. El componente se coloca en la carpeta Shared para su uso en toda la aplicación.

Shared/CultureSelector.razor:

@using  System.Globalization
@inject IJSRuntime JSRuntime
@inject NavigationManager Nav

<p>
    <label>
        Select your locale:
        <select @bind="Culture">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CL"),
    };

    private CultureInfo Culture
    {
        get => CultureInfo.CurrentCulture;
        set
        {
            if (CultureInfo.CurrentCulture != value)
            {
                var js = (IJSInProcessRuntime)JSRuntime;
                js.InvokeVoid("blazorCulture.set", value.Name);

                Nav.NavigateTo(Nav.Uri, forceLoad: true);
            }
        }
    }
}

Dentro de la etiqueta de cierre </div> del elemento <div class="main"> en Shared/MainLayout.razor, agregue el componente CultureSelector:

<div class="bottom-row px-4">
    <CultureSelector />
</div>

Entre los ejemplos de ubicaciones en las que una aplicación podría almacenar las preferencias de un usuario se incluyen el almacenamiento local del explorador (común en las aplicaciones Blazor WebAssembly), en una localización cookie o base de datos (común en las aplicaciones de Blazor Server) o en un servicio externo asociado a una base de datos externa y al que tiene acceso una API web. En el siguiente ejemplo se muestra cómo usar una cookie de localización.

Agregue la referencia del proyecto del paquete Microsoft.Extensions.Localization al archivo del proyecto de la aplicación (.csproj):

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Localization" Version="{VERSION}" />
</ItemGroup>

El marcador de posición {VERSION} de la referencia del paquete anterior es la versión del paquete.

Las aplicaciones Blazor Server se localizan usando un middleware de localización. Agregue servicios de localización a la aplicación con AddLocalization.

En Program.cs:

builder.Services.AddLocalization();

Establezca las referencia culturales predeterminadas y admitidas de la aplicación con RequestLocalizationOptions.SetDefaultCulture.

En Program.cs, inmediatamente después de agregar el middleware de enrutamiento a la canalización de procesamiento:

var supportedCultures = new[] { "en-US", "es-CL" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Program.cs, vea Middleware de ASP.NET Core.

En el siguiente ejemplo se muestra cómo establecer la referencia cultural actual en una cookie que el middleware de localización puede leer.

Agregue los siguientes espacios de nombres en la parte superior del archivo Pages/_Layout.cshtml:

@using System.Globalization
@using Microsoft.AspNetCore.Localization

Inmediatamente después de la etiqueta de apertura <body> de Pages/_Layout.cshtml, agregue la siguiente expresión Razor:

@{
    this.HttpContext.Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(
            new RequestCulture(
                CultureInfo.CurrentCulture,
                CultureInfo.CurrentUICulture)));
}

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Program.cs, vea Middleware de ASP.NET Core.

Si la aplicación no está configurada para procesar acciones del controlador:

• Agregue servicios de MVC mediante una llamada a AddControllers en la colección de servicios en Program.cs:

  builder.Services.AddControllers();
  

• Agregue el enrutamiento del punto de conexión del controlador en Program.cs mediante una llamada a MapControllers en IEndpointRouteBuilder:

  app.MapControllers();
  

  En el ejemplo siguiente se muestra la llamada a UseEndpoints después de agregar la línea:

  app.MapControllers();
  app.MapBlazorHub();
  app.MapFallbackToPage("/_Host");
  

Para especificar una interfaz de usuario que permita a un usuario seleccionar una referencia cultural, se use un método basado en el redireccionamiento con una cookie de localización. La aplicación conserva la referencia cultural seleccionada por el usuario a través de un redireccionamiento a un controlador. Este controlador establece la referencia cultural seleccionada del usuario en una cookie y redirige al usuario de nuevo al URI original. El proceso es similar a lo que ocurre en una aplicación web cuando un usuario intenta acceder a un recurso seguro, donde se redirige al usuario a una página de inicio de sesión y, después, se le redirige nuevamente de vuelta al recurso original.

Controllers/CultureController.cs:

using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;

[Route("[controller]/[action]")]
public class CultureController : Controller
{
    public IActionResult Set(string culture, string redirectUri)
    {
        if (culture != null)
        {
            HttpContext.Response.Cookies.Append(
                CookieRequestCultureProvider.DefaultCookieName,
                CookieRequestCultureProvider.MakeCookieValue(
                    new RequestCulture(culture, culture)));
        }

        return LocalRedirect(redirectUri);
    }
}

El siguiente componente CultureSelector muestra cómo realizar el redireccionamiento inicial cuando el usuario selecciona una referencia cultural. El componente se coloca en la carpeta Shared para su uso en toda la aplicación.

Shared/CultureSelector.razor:

@using  System.Globalization
@inject NavigationManager Nav

<p>
    <label>
        Select your locale:
        <select @bind="Culture">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CL"),
    };

    protected override void OnInitialized()
    {
        Culture = CultureInfo.CurrentCulture;
    }

    private CultureInfo Culture
    {
        get => CultureInfo.CurrentCulture;
        set
        {
            if (CultureInfo.CurrentCulture != value)
            {
                var uri = new Uri(Nav.Uri)
                    .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
                var cultureEscaped = Uri.EscapeDataString(value.Name);
                var uriEscaped = Uri.EscapeDataString(uri);

                Nav.NavigateTo(
                    $"Culture/Set?culture={cultureEscaped}&redirectUri={uriEscaped}",
                    forceLoad: true);
            }
        }
    }
}

Dentro de la etiqueta de cierre </div> del elemento <div class="main"> en Shared/MainLayout.razor, agregue el componente CultureSelector:

<div class="bottom-row px-4">
    <CultureSelector />
</div>

Establezca la propiedad BlazorWebAssemblyLoadAllGlobalizationData en true en el archivo del proyecto de la aplicación (.csproj):

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

En Program.cs, agregue el espacio de nombres para System.Globalization en la parte superior del archivo:

using System.Globalization;

Agregue el servicio de localización de Blazor a la colección de servicios de la aplicación con AddLocalization en Program.cs:

builder.Services.AddLocalization();

Use el middleware de localización para establecer la referencia cultural de la aplicación.

Si la aplicación aún no admite la selección de referencia cultural tratada en la sección Establecimiento dinámico de la referencia cultural según las preferencias del usuario de este artículo:

• Agregue servicios de localización a la aplicación con AddLocalization.
• Especifique las referencia culturales predeterminadas y admitidas de la aplicación en Program.cs. En el ejemplo siguiente se configuran las referencia culturales admitidas para inglés de Estados Unidos y español de Chile.

En Program.cs:

builder.Services.AddLocalization();

En Program.cs, inmediatamente después de agregar el middleware de enrutamiento a la canalización de procesamiento:

var supportedCultures = new[] { "en-US", "es-CL" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Program.cs, vea Middleware de ASP.NET Core.

Si la aplicación debe localizar los recursos en función del almacenamiento de la configuración de referencia cultural de un usuario, use una referencia cultural de localización cookie. El uso de una cookie garantiza que la conexión WebSocket puede propagar correctamente la referencia cultural. Si los esquemas de localización se basan en la ruta de acceso URL o en la cadena de consulta, puede que el esquema no funcione con WebSockets, por lo que no se podrá conservar la referencia cultural. Por lo tanto, el enfoque recomendado es usar una cookie de referencia cultural de localización. Consulte la sección Establecimiento dinámico de la referencia cultural según las preferencias del usuario de este artículo para ver una expresión Razor de ejemplo para el archivo Pages/_Layout.cshtml que conserva la selección de referencia cultural del usuario.

Establezca la propiedad BlazorWebAssemblyLoadAllGlobalizationData en true en el archivo del proyecto de la aplicación (.csproj):

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Las aplicaciones Blazor Server se localizan usando un middleware de localización. Agregue servicios de localización a la aplicación con AddLocalization.

En Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

Especifique las referencia culturales admitidas de la aplicación en Startup.Configure (Startup.cs) inmediatamente después de agregar el middleware de enrutamiento a la canalización de procesamiento. En el ejemplo siguiente se configuran las referencia culturales admitidas para inglés de Estados Unidos y español de Chile:

app.UseRequestLocalization(new RequestLocalizationOptions()
    .AddSupportedCultures(new[] { "en-US", "es-CL" })
    .AddSupportedUICultures(new[] { "en-US", "es-CL" }));

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Startup.Configure, vea Middleware de ASP.NET Core.

Establezca la propiedad BlazorWebAssemblyLoadAllGlobalizationData en true en el archivo del proyecto de la aplicación (.csproj):

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

La referencia cultural de la aplicación se puede establecer en JavaScript cuando Blazor comienza con la opción de inicio applicationCulture de Blazor. En el ejemplo siguiente se configura la aplicación para que se inicie con la referencia cultural de inglés de Estados Unidos (en-US).

• En wwwroot/index.html, evite el inicio automático de Blazor agregando autostart="false" a la etiqueta <script> de Blazor:

  <script src="_framework/blazor.webassembly.js" autostart="false"></script>
  

• Agregue el siguiente bloque <script> después de la etiqueta <script> de Blazor y antes de la etiqueta </body> de cierre:

  <script>
    Blazor.start({
      applicationCulture: 'en-US'
    });
  </script>
  

El valor de applicationCulture debe ajustarse al formato de etiqueta de idioma BCP-47. Para más información sobre el inicio de Blazor, vea Inicio de Blazor en ASP.NET Core.

Una alternativa a establecer la opción de inicio Blazor de la referencia cultural es definir la referencia cultural en código de C#. Establezca CultureInfo.DefaultThreadCurrentCulture y CultureInfo.DefaultThreadCurrentUICulture en Program.cs.

Agregue el espacio de nombres System.Globalization a Program.cs:

using System.Globalization;

Agregue la configuración de la referencia cultural antes de la línea que compila y ejecuta WebAssemblyHostBuilder (await builder.Build().RunAsync();):

CultureInfo.DefaultThreadCurrentCulture = new CultureInfo("en-US");
CultureInfo.DefaultThreadCurrentUICulture = new CultureInfo("en-US");

Las aplicaciones Blazor Server se localizan usando un middleware de localización. Agregue servicios de localización a la aplicación con AddLocalization.

En Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

Especifique la referencia cultural estática en Startup.Configure (Startup.cs) inmediatamente después de agregar el middleware de enrutamiento a la canalización de procesamiento. En el ejemplo siguiente se configura inglés de Estados Unidos:

app.UseRequestLocalization("en-US");

El valor de la referencia cultural de UseRequestLocalization debe ajustarse al formato de etiqueta de idioma BCP-47.

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Startup.Configure, vea Middleware de ASP.NET Core.

Entre los ejemplos de ubicaciones en las que una aplicación podría almacenar las preferencias de un usuario se incluyen el almacenamiento local del explorador (común en las aplicaciones Blazor WebAssembly), en una localización cookie o base de datos (común en las aplicaciones de Blazor Server) o en un servicio externo asociado a una base de datos externa y al que tiene acceso una API web. En el ejemplo siguiente se muestra cómo usar el almacenamiento local del explorador.

Agregue la referencia del proyecto del paquete Microsoft.Extensions.Localization al archivo del proyecto de la aplicación (.csproj):

<PackageReference Include="Microsoft.Extensions.Localization" Version="{VERSION}" />

El marcador de posición {VERSION} de la referencia del paquete anterior es la versión del paquete.

Establezca la propiedad BlazorWebAssemblyLoadAllGlobalizationData en true en el archivo del proyecto:

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

La referencia cultural de la aplicación en una aplicación Blazor WebAssembly se establece mediante la API del marco de Blazor. La selección de la referencia cultural de un usuario se puede conservar en el almacenamiento local del explorador.

En el archivo wwwroot/index.html después de la etiqueta <script> de Blazor y antes de la etiqueta de cierre </body>, proporcione funciones de JS para obtener y establecer la selección de la referencia cultural del usuario con el almacenamiento local del explorador:

<script>
  window.blazorCulture = {
    get: () => window.localStorage['BlazorCulture'],
    set: (value) => window.localStorage['BlazorCulture'] = value
  };
</script>

export function getBlazorCulture() {
  return window.localStorage['BlazorCulture'];
};
export function setBlazorCulture(value) {
  window.localStorage['BlazorCulture'] = value;
};

Agregue los espacios de nombres para System.Globalization y Microsoft.JSInterop en la parte superior de Program.cs:

using System.Globalization;
using Microsoft.JSInterop;

Quite las siguientes líneas de Program.cs:

- await builder.Build().RunAsync();

Reemplace la línea anterior por el código siguiente. El código agrega el servicio de localización de Blazor a la colección de servicios de la aplicación con AddLocalization y usa la interoperabilidad de JS para llamar a JS y recuperar la selección de referencia cultural del usuario del almacenamiento local. Si el almacenamiento local no contiene ninguna referencia cultural para el usuario, el código establece un valor predeterminado de inglés de Estados Unidos (en-US).

builder.Services.AddLocalization();

var host = builder.Build();

CultureInfo culture;
var js = host.Services.GetRequiredService<IJSRuntime>();
var result = await js.InvokeAsync<string>("blazorCulture.get");

if (result != null)
{
    culture = new CultureInfo(result);
}
else
{
    culture = new CultureInfo("en-US");
    await js.InvokeVoidAsync("blazorCulture.set", "en-US");
}

CultureInfo.DefaultThreadCurrentCulture = culture;
CultureInfo.DefaultThreadCurrentUICulture = culture;

await host.RunAsync();

El componente CultureSelector siguiente muestra cómo establecer la selección de referencia cultural del usuario en el almacenamiento local del explorador mediante la interoperabilidad de JS. El componente se coloca en la carpeta Shared para su uso en toda la aplicación.

Shared/CultureSelector.razor:

@using  System.Globalization
@inject IJSRuntime JSRuntime
@inject NavigationManager Nav

<p>
    <label>
        Select your locale:
        <select @bind="Culture">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CL"),
    };

    private CultureInfo Culture
    {
        get => CultureInfo.CurrentCulture;
        set
        {
            if (CultureInfo.CurrentCulture != value)
            {
                var js = (IJSInProcessRuntime)JSRuntime;
                js.InvokeVoid("blazorCulture.set", value.Name);

                Nav.NavigateTo(Nav.Uri, forceLoad: true);
            }
        }
    }
}

Dentro de la etiqueta de cierre </div> del elemento <div class="main"> en Shared/MainLayout.razor, agregue el componente CultureSelector:

<div class="bottom-row px-4">
    <CultureSelector />
</div>

Entre los ejemplos de ubicaciones en las que una aplicación podría almacenar las preferencias de un usuario se incluyen el almacenamiento local del explorador (común en las aplicaciones Blazor WebAssembly), en una localización cookie o base de datos (común en las aplicaciones de Blazor Server) o en un servicio externo asociado a una base de datos externa y al que tiene acceso una API web. En el siguiente ejemplo se muestra cómo usar una cookie de localización.

Agregue la referencia del proyecto del paquete Microsoft.Extensions.Localization al archivo del proyecto de la aplicación (.csproj):

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Localization" Version="{VERSION}" />
</ItemGroup>

El marcador de posición {VERSION} de la referencia del paquete anterior es la versión del paquete.

Las aplicaciones Blazor Server se localizan usando un middleware de localización. Agregue servicios de localización a la aplicación con AddLocalization.

En Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

Establezca las referencia culturales predeterminadas y admitidas de la aplicación con RequestLocalizationOptions.SetDefaultCulture.

En Startup.Configure, inmediatamente después de agregar el middleware de enrutamiento a la canalización de procesamiento:

var supportedCultures = new[] { "en-US", "es-CL" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Startup.Configure, vea Middleware de ASP.NET Core.

En el siguiente ejemplo se muestra cómo establecer la referencia cultural actual en una cookie que el middleware de localización puede leer.

Agregue los siguientes espacios de nombres en la parte superior del archivo Pages/_Host.cshtml:

@using System.Globalization
@using Microsoft.AspNetCore.Localization

Inmediatamente después de la etiqueta de apertura <body> de Pages/_Host.cshtml, agregue la siguiente expresión Razor:

@{
    this.HttpContext.Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(
            new RequestCulture(
                CultureInfo.CurrentCulture,
                CultureInfo.CurrentUICulture)));
}

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Startup.Configure, vea Middleware de ASP.NET Core.

Si la aplicación no está configurada para procesar acciones del controlador:

• Agregue servicios de MVC mediante una llamada a AddControllers en la colección de servicios en Startup.ConfigureServices:

  services.AddControllers();
  

• Agregue el enrutamiento del punto de conexión del controlador en Startup.Configure mediante una llamada a MapControllers en IEndpointRouteBuilder:

  endpoints.MapControllers();
  

  En el ejemplo siguiente se muestra la llamada a UseEndpoints después de agregar la línea:

  app.UseEndpoints(endpoints =>
  {
  +   endpoints.MapControllers();
      endpoints.MapBlazorHub();
      endpoints.MapFallbackToPage("/_Host");
  });
  

Para especificar una interfaz de usuario que permita a un usuario seleccionar una referencia cultural, se use un método basado en el redireccionamiento con una cookie de localización. La aplicación conserva la referencia cultural seleccionada por el usuario a través de un redireccionamiento a un controlador. Este controlador establece la referencia cultural seleccionada del usuario en una cookie y redirige al usuario de nuevo al URI original. El proceso es similar a lo que ocurre en una aplicación web cuando un usuario intenta acceder a un recurso seguro, donde se redirige al usuario a una página de inicio de sesión y, después, se le redirige nuevamente de vuelta al recurso original.

Controllers/CultureController.cs:

using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;

[Route("[controller]/[action]")]
public class CultureController : Controller
{
    public IActionResult Set(string culture, string redirectUri)
    {
        if (culture != null)
        {
            HttpContext.Response.Cookies.Append(
                CookieRequestCultureProvider.DefaultCookieName,
                CookieRequestCultureProvider.MakeCookieValue(
                    new RequestCulture(culture, culture)));
        }

        return LocalRedirect(redirectUri);
    }
}

El siguiente componente CultureSelector muestra cómo realizar el redireccionamiento inicial cuando el usuario selecciona una referencia cultural. El componente se coloca en la carpeta Shared para su uso en toda la aplicación.

Shared/CultureSelector.razor:

@using  System.Globalization
@inject NavigationManager Nav

<p>
    <label>
        Select your locale:
        <select @bind="Culture">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CL"),
    };

    protected override void OnInitialized()
    {
        Culture = CultureInfo.CurrentCulture;
    }

    private CultureInfo Culture
    {
        get => CultureInfo.CurrentCulture;
        set
        {
            if (CultureInfo.CurrentCulture != value)
            {
                var uri = new Uri(Nav.Uri)
                    .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
                var cultureEscaped = Uri.EscapeDataString(value.Name);
                var uriEscaped = Uri.EscapeDataString(uri);

                Nav.NavigateTo(
                    $"Culture/Set?culture={cultureEscaped}&redirectUri={uriEscaped}",
                    forceLoad: true);
            }
        }
    }
}

Dentro de la etiqueta de cierre </div> del elemento <div class="main"> en Shared/MainLayout.razor, agregue el componente CultureSelector:

<div class="bottom-row px-4">
    <CultureSelector />
</div>

Establezca la propiedad BlazorWebAssemblyLoadAllGlobalizationData en true en el archivo del proyecto de la aplicación (.csproj):

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

En Program.cs, agregue el espacio de nombres para System.Globalization en la parte superior del archivo:

using System.Globalization;

Agregue el servicio de localización de Blazor a la colección de servicios de la aplicación con AddLocalization en Program.cs:

builder.Services.AddLocalization();

Use el middleware de localización para establecer la referencia cultural de la aplicación.

Si la aplicación aún no admite la selección de referencia cultural tratada en la sección Establecimiento dinámico de la referencia cultural según las preferencias del usuario de este artículo:

• Agregue servicios de localización a la aplicación con AddLocalization.
• Especifique las referencia culturales predeterminadas y admitidas de la aplicación en Startup.Configure (Startup.cs). En el ejemplo siguiente se configuran las referencia culturales admitidas para inglés de Estados Unidos y español de Chile.

En Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

En Startup.Configure, inmediatamente después de agregar el middleware de enrutamiento a la canalización de procesamiento:

var supportedCultures = new[] { "en-US", "es-CL" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Startup.Configure, vea Middleware de ASP.NET Core.

Si la aplicación debe localizar los recursos en función del almacenamiento de la configuración de referencia cultural de un usuario, use una referencia cultural de localización cookie. El uso de una cookie garantiza que la conexión WebSocket puede propagar correctamente la referencia cultural. Si los esquemas de localización se basan en la ruta de acceso URL o en la cadena de consulta, puede que el esquema no funcione con WebSockets, por lo que no se podrá conservar la referencia cultural. Por lo tanto, el enfoque recomendado es usar una cookie de referencia cultural de localización. Consulte la sección Establecimiento dinámico de la referencia cultural según las preferencias del usuario de este artículo para ver una expresión Razor de ejemplo para el archivo Pages/_Host.cshtml que conserva la selección de referencia cultural del usuario.

Las aplicaciones Blazor Server se localizan usando un middleware de localización. Agregue servicios de localización a la aplicación con AddLocalization.

En Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

Especifique las referencia culturales admitidas de la aplicación en Startup.Configure (Startup.cs) inmediatamente después de agregar el middleware de enrutamiento a la canalización de procesamiento. En el ejemplo siguiente se configuran las referencia culturales admitidas para inglés de Estados Unidos y español de Chile:

app.UseRequestLocalization(new RequestLocalizationOptions()
    .AddSupportedCultures(new[] { "en-US", "es-CL" })
    .AddSupportedUICultures(new[] { "en-US", "es-CL" }));

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Startup.Configure, vea Middleware de ASP.NET Core.

De forma predeterminada, la configuración del enlazador de lenguaje intermedio (IL) para aplicaciones de Blazor WebAssembly quita la información de internacionalización, excepto para las configuraciones regionales solicitadas de forma explícita. Para obtener más información, vea Configuración del enlazador de ASP.NET Core Blazor.

Las aplicaciones Blazor Server se localizan usando un middleware de localización. Agregue servicios de localización a la aplicación con AddLocalization.

En Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

Especifique la referencia cultural estática en Startup.Configure (Startup.cs) inmediatamente después de agregar el middleware de enrutamiento a la canalización de procesamiento. En el ejemplo siguiente se configura inglés de Estados Unidos:

app.UseRequestLocalization("en-US");

El valor de la referencia cultural de UseRequestLocalization debe ajustarse al formato de etiqueta de idioma BCP-47.

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Startup.Configure, vea Middleware de ASP.NET Core.

Entre los ejemplos de ubicaciones en las que una aplicación podría almacenar las preferencias de un usuario se incluyen el almacenamiento local del explorador (común en las aplicaciones Blazor WebAssembly), en una localización cookie o base de datos (común en las aplicaciones de Blazor Server) o en un servicio externo asociado a una base de datos externa y al que tiene acceso una API web. En el ejemplo siguiente se muestra cómo usar el almacenamiento local del explorador.

Agregue la referencia del proyecto del paquete Microsoft.Extensions.Localization al archivo del proyecto de la aplicación (.csproj):

<PackageReference Include="Microsoft.Extensions.Localization" Version="{VERSION}" />

El marcador de posición {VERSION} de la referencia del paquete anterior es la versión del paquete.

La referencia cultural de la aplicación en una aplicación Blazor WebAssembly se establece mediante la API del marco de Blazor. La selección de la referencia cultural de un usuario se puede conservar en el almacenamiento local del explorador.

En el archivo wwwroot/index.html después de la etiqueta <script> de Blazor y antes de la etiqueta de cierre </body>, proporcione funciones de JS para obtener y establecer la selección de la referencia cultural del usuario con el almacenamiento local del explorador:

<script>
  window.blazorCulture = {
    get: () => window.localStorage['BlazorCulture'],
    set: (value) => window.localStorage['BlazorCulture'] = value
  };
</script>

Agregue los espacios de nombres para System.Globalization y Microsoft.JSInterop en la parte superior de Program.cs:

using System.Globalization;
using Microsoft.JSInterop;

Quite las siguientes líneas de Program.cs:

-await builder.Build().RunAsync();

Reemplace la línea anterior por el código siguiente. El código agrega el servicio de localización de Blazor a la colección de servicios de la aplicación con AddLocalization y usa la interoperabilidad de JS para llamar a JS y recuperar la selección de referencia cultural del usuario del almacenamiento local. Si el almacenamiento local no contiene ninguna referencia cultural para el usuario, el código establece un valor predeterminado de inglés de Estados Unidos (en-US).

builder.Services.AddLocalization();

var host = builder.Build();

CultureInfo culture;
var js = host.Services.GetRequiredService<IJSRuntime>();
var result = await js.InvokeAsync<string>("blazorCulture.get");

if (result != null)
{
    culture = new CultureInfo(result);
}
else
{
    culture = new CultureInfo("en-US");
    await js.InvokeVoidAsync("blazorCulture.set", "en-US");
}

CultureInfo.DefaultThreadCurrentCulture = culture;
CultureInfo.DefaultThreadCurrentUICulture = culture;

await host.RunAsync();

El componente CultureSelector siguiente muestra cómo establecer la selección de referencia cultural del usuario en el almacenamiento local del explorador mediante la interoperabilidad de JS. El componente se coloca en la carpeta Shared para su uso en toda la aplicación.

Shared/CultureSelector.razor:

@using  System.Globalization
@inject IJSRuntime JSRuntime
@inject NavigationManager Nav

<p>
    <label>
        Select your locale:
        <select @bind="Culture">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CL"),
    };

    private CultureInfo Culture
    {
        get => CultureInfo.CurrentCulture;
        set
        {
            if (CultureInfo.CurrentCulture != value)
            {
                var js = (IJSInProcessRuntime)JSRuntime;
                js.InvokeVoid("blazorCulture.set", value.Name);

                Nav.NavigateTo(Nav.Uri, forceLoad: true);
            }
        }
    }
}

Dentro de la etiqueta de cierre </div> del elemento <div class="main"> en Shared/MainLayout.razor, agregue el componente CultureSelector:

<div class="bottom-row px-4">
    <CultureSelector />
</div>

Entre los ejemplos de ubicaciones en las que una aplicación podría almacenar las preferencias de un usuario se incluyen el almacenamiento local del explorador (común en las aplicaciones Blazor WebAssembly), en una localización cookie o base de datos (común en las aplicaciones de Blazor Server) o en un servicio externo asociado a una base de datos externa y al que tiene acceso una API web. En el siguiente ejemplo se muestra cómo usar una cookie de localización.

Agregue la referencia del proyecto del paquete Microsoft.Extensions.Localization al archivo del proyecto de la aplicación (.csproj):

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Localization" Version="{VERSION}" />
</ItemGroup>

El marcador de posición {VERSION} de la referencia del paquete anterior es la versión del paquete.

Las aplicaciones Blazor Server se localizan usando un middleware de localización. Agregue servicios de localización a la aplicación con AddLocalization.

En Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

Establezca las referencia culturales predeterminadas y admitidas de la aplicación con RequestLocalizationOptions.SetDefaultCulture.

En Startup.Configure, inmediatamente después de agregar el middleware de enrutamiento a la canalización de procesamiento:

var supportedCultures = new[] { "en-US", "es-CL" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Startup.Configure, vea Middleware de ASP.NET Core.

En el siguiente ejemplo se muestra cómo establecer la referencia cultural actual en una cookie que el middleware de localización puede leer.

Agregue los siguientes espacios de nombres en la parte superior del archivo Pages/_Host.cshtml:

@using System.Globalization
@using Microsoft.AspNetCore.Localization

Inmediatamente después de la etiqueta de apertura <body> de Pages/_Host.cshtml, agregue la siguiente expresión Razor:

@{
    this.HttpContext.Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(
            new RequestCulture(
                CultureInfo.CurrentCulture,
                CultureInfo.CurrentUICulture)));
}

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Startup.Configure, vea Middleware de ASP.NET Core.

Si la aplicación no está configurada para procesar acciones del controlador:

• Agregue servicios de MVC mediante una llamada a AddControllers en la colección de servicios en Startup.ConfigureServices:

  services.AddControllers();
  

• Agregue el enrutamiento del punto de conexión del controlador en Startup.Configure mediante una llamada a MapControllers en IEndpointRouteBuilder:

  endpoints.MapControllers();
  

  En el ejemplo siguiente se muestra la llamada a UseEndpoints después de agregar la línea:

  app.UseEndpoints(endpoints =>
  {
  +   endpoints.MapControllers();
      endpoints.MapBlazorHub();
      endpoints.MapFallbackToPage("/_Host");
  });
  

Para especificar una interfaz de usuario que permita a un usuario seleccionar una referencia cultural, se use un método basado en el redireccionamiento con una cookie de localización. La aplicación conserva la referencia cultural seleccionada por el usuario a través de un redireccionamiento a un controlador. Este controlador establece la referencia cultural seleccionada del usuario en una cookie y redirige al usuario de nuevo al URI original. El proceso es similar a lo que ocurre en una aplicación web cuando un usuario intenta acceder a un recurso seguro, donde se redirige al usuario a una página de inicio de sesión y, después, se le redirige nuevamente de vuelta al recurso original.

Controllers/CultureController.cs:

using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;

[Route("[controller]/[action]")]
public class CultureController : Controller
{
    public IActionResult Set(string culture, string redirectUri)
    {
        if (culture != null)
        {
            HttpContext.Response.Cookies.Append(
                CookieRequestCultureProvider.DefaultCookieName,
                CookieRequestCultureProvider.MakeCookieValue(
                    new RequestCulture(culture, culture)));
        }

        return LocalRedirect(redirectUri);
    }
}

El siguiente componente CultureSelector muestra cómo realizar el redireccionamiento inicial cuando el usuario selecciona una referencia cultural. El componente se coloca en la carpeta Shared para su uso en toda la aplicación.

Shared/CultureSelector.razor:

@using  System.Globalization
@inject NavigationManager Nav

<p>
    <label>
        Select your locale:
        <select @bind="Culture">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CL"),
    };

    protected override void OnInitialized()
    {
        Culture = CultureInfo.CurrentCulture;
    }

    private CultureInfo Culture
    {
        get => CultureInfo.CurrentCulture;
        set
        {
            if (CultureInfo.CurrentCulture != value)
            {
                var uri = new Uri(Nav.Uri)
                    .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
                var cultureEscaped = Uri.EscapeDataString(value.Name);
                var uriEscaped = Uri.EscapeDataString(uri);

                Nav.NavigateTo(
                    $"Culture/Set?culture={cultureEscaped}&redirectUri={uriEscaped}",
                    forceLoad: true);
            }
        }
    }
}

Dentro de la etiqueta de cierre </div> del elemento <div class="main"> en Shared/MainLayout.razor, agregue el componente CultureSelector:

<div class="bottom-row px-4">
    <CultureSelector />
</div>

De forma predeterminada, la configuración del enlazador de lenguaje intermedio (IL) para aplicaciones de Blazor WebAssembly quita la información de internacionalización, excepto para las configuraciones regionales solicitadas de forma explícita. Para obtener más información, vea Configuración del enlazador de ASP.NET Core Blazor.

En Program.cs, agregue el espacio de nombres para System.Globalization en la parte superior del archivo:

using System.Globalization;

Agregue el servicio de localización de Blazor a la colección de servicios de la aplicación con AddLocalization en Program.cs:

builder.Services.AddLocalization();

Use el middleware de localización para establecer la referencia cultural de la aplicación.

Si la aplicación aún no admite la selección de referencia cultural tratada en la sección Establecimiento dinámico de la referencia cultural según las preferencias del usuario de este artículo:

• Agregue servicios de localización a la aplicación con AddLocalization.
• Especifique las referencia culturales predeterminadas y admitidas de la aplicación en Startup.Configure (Startup.cs). En el ejemplo siguiente se configuran las referencia culturales admitidas para inglés de Estados Unidos y español de Chile.

En Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

En Startup.Configure, inmediatamente después de agregar el middleware de enrutamiento a la canalización de procesamiento:

var supportedCultures = new[] { "en-US", "es-CL" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

Para obtener información sobre cómo ordenar el middleware de localización en la canalización de middleware de Startup.Configure, vea Middleware de ASP.NET Core.

Si la aplicación debe localizar los recursos en función del almacenamiento de la configuración de referencia cultural de un usuario, use una referencia cultural de localización cookie. El uso de una cookie garantiza que la conexión WebSocket puede propagar correctamente la referencia cultural. Si los esquemas de localización se basan en la ruta de acceso URL o en la cadena de consulta, puede que el esquema no funcione con WebSockets, por lo que no se podrá conservar la referencia cultural. Por lo tanto, el enfoque recomendado es usar una cookie de referencia cultural de localización. Consulte la sección Establecimiento dinámico de la referencia cultural según las preferencias del usuario de este artículo para ver una expresión Razor de ejemplo para el archivo Pages/_Host.cshtml que conserva la selección de referencia cultural del usuario.