지역화된 ASP.NET Core 앱에서 각 요청에 대한 언어/문화권을 선택하는 전략 구현

Hisham Bin Ateya, Damien Bowden, Bart Calixto, Nadeem Afana, Rick Anderson

앱을 지역화하는 한 가지 작업은 앱이 반환하는 각 응답에 적절한 문화권을 선택하는 전략을 구현하는 것입니다.

지역화 미들웨어 구성

요청에서 현재 문화권은 지역화 미들웨어에서 설정됩니다. 에서 지역화 미들웨어를 사용할 수 있습니다 Program.cs. 지역화 미들웨어는 요청 문화권을 확인할 수 있는 모든 미들웨어 전에 구성되어야 합니다(예: app.UseMvcWithDefaultRoute()).

builder.Services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[] { "en-US", "fr" };
    options.SetDefaultCulture(supportedCultures[0])
        .AddSupportedCultures(supportedCultures)
        .AddSupportedUICultures(supportedCultures);
});

UseRequestLocalization은 RequestLocalizationOptions 개체를 초기화합니다. 모든 요청의 RequestLocalizationOptions에서 RequestCultureProvider의 목록이 열거되고 요청 문화권을 성공적으로 결정할 수 있는 첫 번째 공급자가 사용됩니다. 기본 공급자는 RequestLocalizationOptions 클래스에서 제공됩니다.

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

기본 목록은 가장 구체적인 것에서 덜 구체적으로 것으로 이동합니다. 이 문서의 뒷부분에서는 순서를 변경하고 사용자 지정 문화권 공급자를 추가하는 방법을 확인할 수 있습니다. 공급자가 요청 문화권을 확인할 수 없는 경우 DefaultRequestCulture가 사용됩니다.

QueryStringRequestCultureProvider

일부 앱은 쿼리 문자열 CultureInfo을 사용하여 . cookie 또는 수용-언어 헤더 방식을 사용하는 앱의 경우 URL에 쿼리 문자열을 추가하는 것은 코드 디버깅 및 테스트에 유용합니다. 기본적으로 QueryStringRequestCultureProvider는 RequestCultureProvider 목록에서 첫 번째 지역화 공급자로 등록됩니다. culture 및 ui-culture에 쿼리 문자열 매개 변수를 전달합니다. 다음 예제는 특정 문화권(언어 및 지역)을 스페인어/멕시코로 설정합니다.

http://localhost:5000/?culture=es-MX&ui-culture=es-MX

쿼리 문자열 공급자는 culture 전달된 값을 사용하여 두 값을 모두 설정하거나 ui-culture 전달합니다. 예를 들어 문화권만을 설정하면 Culture 및 UICulture 모두를 설정합니다.

http://localhost:5000/?culture=es-MX

CookieRequestCultureProvider

프로덕션 앱은 종종 메커니즘을 제공하여 ASP.NET Core 문화권 cookie로 문화권을 설정합니다. MakeCookieValue 메서드를 사용하여 cookie를 만듭니다.

CookieRequestCultureProviderDefaultCookieName은 사용자의 기본 문화권 정보를 추적하는 데 사용되는 기본 cookie 이름을 반환합니다. 기본 cookie 이름은 .AspNetCore.Culture입니다.

cookie 형식은 c=%LANGCODE%|uic=%LANGCODE%이며, 여기서 c는 Culture이고 uic는 UICulture입니다. 예를 들면 다음과 같습니다.

c=en-UK|uic=en-US

문화권 정보 또는 UI 문화권 중 하나만 제공된 경우 제공된 문화권은 문화권 정보와 UI 문화권 모두에 사용됩니다.

수용-언어 HTTP 헤더

수용-언어 헤더는 대부분의 브라우저에서 설정할 수 있으며 원래 사용자의 언어를 지정하도록 계획되었습니다. 이 설정은 브라우저가 전송하도록 설정된 것 또는 기본 운영 체제에서 상속한 것을 나타냅니다. 브라우저 요청에서 수용-언어 HTTP 헤더는 사용자의 기본 언어를 검색하는 확실한 방법이 아닙니다(브라우저에서 언어 기본 설정 설정 참조). 프로덕션 앱은 사용자가 선택한 문화권을 사용자 지정하는 방법을 포함해야 합니다.

Edge에서 Accept-Language HTTP 헤더 설정

1. 기본 설정 언어를 설정 검색합니다.

2. 기본 설정 언어는 기본 설정 언어 상자에 나열 됩니다 .

3. 목록에 추가할 언어 추가를 선택합니다.

4. 언어 옆에 있는 추가 작업을 선택하여 기본 설정 순서를 변경합니다.

콘텐츠-언어 HTTP 헤더

콘텐츠-언어 엔터티 헤더:

• 대상 그룹을 위한 언어를 설명하는 데 사용됩니다.
• 사용자가 사용자 기본 설정 언어에 따라 구별할 수 있습니다.

엔터티 헤더는 HTTP 요청 및 응답에 모두 사용됩니다.

속성 ApplyCurrentCultureToResponseHeaders을(를) 설정하여 Content-Language 헤더를 추가할 수 있습니다.

Content-Language 헤더 추가:

• 를 사용하여 RequestLocalizationMiddleware 헤더를 Content-Language 설정할 수 있습니다 CurrentUICulture.
• 응답 헤더 Content-Language를 명시적으로 설정하지 않아도 됩니다.

app.UseRequestLocalization(new RequestLocalizationOptions
{
    ApplyCurrentCultureToResponseHeaders = true
});

RouteDataRequest CultureProvider 적용

RouteDataRequestCultureProvider 경로 값의 값을 기반으로 문화권을 culture 설정합니다. 다음 정보에 대한 필터로 미들웨어를 사용하는 URL 문화권 공급자를 참조하세요.

• 미들웨어를 ASP.NET Core의 필터 기능으로 사용합니다.
• URL에서 앱의 문화권을 설정하는 데 사용하는 RouteDataRequestCultureProvider 방법입니다.

전역적으로 적용하는 방법에 대한 자세한 내용은 미들웨어를 사용하여 RouteDataRequest CultureProvider를 전역적으로 적용 RouteDataRequestCultureProvider 하는 방법을 참조하세요.

사용자 지정 공급자 사용

소비자가 자신의 언어 및 문화권을 데이터베이스에 저장하도록 하기를 원한다고 가정합니다. 공급자를 작성하여 사용자에 대한 이러한 값을 조회할 수 있습니다. 다음 코드에서는 사용자 지정 공급자를 추가하는 방법을 보여 줍니다.

private const string enUSCulture = "en-US";

services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[]
    {
        new CultureInfo(enUSCulture),
        new CultureInfo("fr")
    };

    options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;

    options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return await Task.FromResult(new ProviderCultureResult("en"));
    }));
});

RequestLocalizationOptions를 사용하여 지역화 공급자를 추가하거나 제거합니다.

변경 요청 문화권 공급자 순서

RequestLocalizationOptions에는 3개의 기본 요청 문화권 공급자가 있습니다. QueryStringRequestCultureProvider, CookieRequestCultureProvider 및 AcceptLanguageHeaderRequestCultureProvider. 이러한 공급자의 순서를 변경하려면 아래 그림과 같이 RequestLocalizationOptions.RequestCultureProviders 속성을 사용합니다.

    app.UseRequestLocalization(options =>
    {
        var questStringCultureProvider = options.RequestCultureProviders[0];    
        options.RequestCultureProviders.RemoveAt(0);
        options.RequestCultureProviders.Insert(1, questStringCultureProvider);
    });

앞의 예제에서는 순서 QueryStringRequestCultureProvider 가 전환되므로 RequestLocalizationMiddleware 첫 번째 문화권에서 쿼리 문자열을 cookie찾 CookieRequestCultureProvider 습니다.

앞서 설명한 대로 0에 순서를 설정하는 AddInitialRequestCultureProvider를 통해 사용자 지정 공급자를 추가합니다. 그러면 이 공급자는 다른 공급자보다 우선 순위가 높아집니다.

사용자 재정의 문화권

RequestLocalizationOptions.CultureInfoUseUserOverride 속성을 사용하면 앱에서 기본값이 아닌 Windows 설정을 및 속성에 CultureInfoDateTimeFormatNumberFormat 사용할지 여부를 결정할 수 있습니다. 이는 Linux에 영향을 주지 않습니다. 이 값은 .에 UseUserOverride직접 해당합니다.

    app.UseRequestLocalization(options =>
    {
        options.CultureInfoUseUserOverride = false;
    });

프로그래밍 방식으로 문화권 설정

GitHub에서 이 샘플 Localization.StarterWeb 프로젝트는 Culture를 설정하는 UI를 포함합니다. 이 Views/Shared/_SelectLanguagePartial.cshtml 파일을 사용하면 지원되는 문화권 목록에서 문화권을 선택할 수 있습니다.

@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Http.Features
@using Microsoft.AspNetCore.Localization
@using Microsoft.AspNetCore.Mvc.Localization
@using Microsoft.Extensions.Options

@inject IViewLocalizer Localizer
@inject IOptions<RequestLocalizationOptions> LocOptions

@{
    var requestCulture = Context.Features.Get<IRequestCultureFeature>();
    var cultureItems = LocOptions.Value.SupportedUICultures
        .Select(c => new SelectListItem { Value = c.Name, Text = c.DisplayName })
        .ToList();
    var returnUrl = string.IsNullOrEmpty(Context.Request.Path) ? "~/" : $"~{Context.Request.Path.Value}";
}

<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">
    <form id="selectLanguage" asp-controller="Home" 
          asp-action="SetLanguage" asp-route-returnUrl="@returnUrl" 
          method="post" class="form-horizontal" role="form">
        <label asp-for="@requestCulture.RequestCulture.UICulture.Name">@Localizer["Language:"]</label> <select name="culture"
          onchange="this.form.submit();"
          asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
        </select>
    </form>
</div>

Views/Shared/_SelectLanguagePartial.cshtml 파일은 레이아웃 파일의 footer 섹션에 추가되므로 모든 보기에서 사용할 수 있습니다.

<div class="container body-content" style="margin-top:60px">
    @RenderBody()
    <hr>
    <footer>
        <div class="row">
            <div class="col-md-6">
                <p>&copy; @System.DateTime.Now.Year - Localization</p>
            </div>
            <div class="col-md-6 text-right">
                @await Html.PartialAsync("_SelectLanguagePartial")
            </div>
        </div>
    </footer>
</div>

SetLanguage 메서드는 문화권 cookie를 설정합니다.

[HttpPost]
public IActionResult SetLanguage(string culture, string returnUrl)
{
    Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),
        new CookieOptions { Expires = DateTimeOffset.UtcNow.AddYears(1) }
    );

    return LocalRedirect(returnUrl);
}

이 프로젝트에 대한 샘플 코드는 _SelectLanguagePartial.cshtml 연결할 수 없습니다. GitHub의 Localization.StarterWeb 프로젝트에는 종속성 주입 컨테이너를 통해 Razor 부분에 RequestLocalizationOptions를 흐르도록 하는 코드가 있습니다.

모델 바인딩 경로 데이터 및 쿼리 문자열

모델 바인딩 경로 데이터 및 쿼리 문자열의 세계화 동작을 참조하세요.

다음 단계

앱 지역화에는 다음 작업도 포함됩니다.

• 앱의 콘텐츠를 지역화할 수 있도록 합니다.
• 앱에서 지원하는 언어 및 문화권에 대한 지역화된 리소스 제공

추가 리소스

• ASP.NET Core에서 미들웨어를 필터로 사용하는 URL 문화권 공급자
• 미들웨어를 필터로 사용하여 RouteDataRequest CultureProvider를 전역적으로 적용
• ASP.NET Core의 세계화 및 지역화
• ASP.NET Core 앱의 콘텐츠를 지역화할 수 있도록 만들기
• ASP.NET Core 앱에서 언어 및 문화권에 대한 지역화된 리소스 제공
• 핵심 지역화 ASP.NET 문제 해결
• .NET 애플리케이션 전역화 및 지역화
• Localization.StarterWeb 프로젝트는 문서에서 사용됩니다.
• .resx 파일의 리소스
• Microsoft 다국어 앱 도구 키트
• 지역화 및 제네릭