ASP.NET Core 지역화 문제 해결Troubleshoot ASP.NET Core Localization

작성자: Hisham Bin AteyaBy Hisham Bin Ateya

이 문서에서는 ASP.NET Core 앱 지역화 문제를 진단하는 방법에 대한 지침을 제공합니다.This article provides instructions on how to diagnose ASP.NET Core app localization issues.

지역화 구성 문제Localization configuration issues

지역화 미들웨어 순서Localization middleware order
지역화 미들웨어가 예상대로 정렬되지 않으므로 앱이 지역화되지 않을 수 있습니다.The app may not localize because the localization middleware isn't ordered as expected.

이 문제를 해결하려면 해당 지역화 미들웨어가 MVC 미들웨어 전에 등록되었는지 확인합니다.To resolve this issue, ensure that localization middleware is registered before MVC middleware. 그렇지 않으면 지역화 미들웨어는 적용되지 않습니다.Otherwise, the localization middleware isn't applied.

public void ConfigureServices(IServiceCollection services)
{
    services.AddLocalization(options => options.ResourcesPath = "Resources");

    services.AddMvc();
}

지역화 리소스 경로가 없음Localization resources path not found

RequestCultureProvider에서 지원되는 문화권이 등록된 문화권과 한 번 일치하지 않음Supported Cultures in RequestCultureProvider don't match with registered once

리소스 파일 이름 지정 문제Resource file naming issues

ASP.NET Core에는 지역화 리소스 파일 이름 지정에 대해 미리 정의된 규칙 지침이 있고 여기에서 자세히 설명합니다.ASP.NET Core has predefined rules and guidelines for localization resources file naming, which are described in detail here.

누락된 리소스Missing resources

리소스를 찾을 수 없는 일반적인 원인은 다음과 같습니다.Common causes of resources not being found include:

  • resx 파일 또는 로컬라이저 요청에서 리소스 이름의 철자가 잘못되었습니다.Resource names are misspelled in either the resx file or the localizer request.
  • 리소스가 일부 언어의 경우 resx에서 누락되었지만 다른 언어에서 존재합니다.The resource is missing from the resx for some languages, but exists in others.
  • 여전히 문제가 있는 경우 누락된 리소스에 대한 자세한 내용은 Debug 로그 수준의 지역화 로그 메시지를 확인하세요.If you're still having trouble, check the localization log messages (which are at Debug log level) for more details about the missing resources.

힌트: CookieRequestCultureProvider를 사용하는 경우 지역화 cookie 값 안의 문화권에서 작은따옴표를 사용하지 않았는지 확인합니다. 예를 들어 c='en-UK'|uic='en-US'가 잘못된 cookie 값인 반면, c=en-UK|uic=en-US는 유효합니다.Hint: When using CookieRequestCultureProvider, verify single quotes are not used with the cultures inside the localization cookie value. For example, c='en-UK'|uic='en-US' is an invalid cookie value, while c=en-UK|uic=en-US is a valid.

리소스 및 클래스 라이브러리 문제Resources & Class Libraries issues

기본적으로 ASP.NET Core는 클래스 라이브러리가 ResourceLocationAttribute를 통해 해당 리소스 파일을 찾을 수 있는 방법을 제공합니다.ASP.NET Core by default provides a way to allow the class libraries to find their resource files via ResourceLocationAttribute.

클래스 라이브러리와 관련된 일반적인 문제는 다음과 같습니다.Common issues with class libraries include:

  • 라이브러리 클래스에서 ResourceLocationAttribute가 누락되면 ResourceManagerStringLocalizerFactory가 리소스를 검색하지 못합니다.Missing the ResourceLocationAttribute in a class library will prevent ResourceManagerStringLocalizerFactory from discovering the resources.
  • 리소스 파일 이름 지정Resource file naming. 자세한 내용은 리소스 파일 이름 지정 문제 섹션을 참조하세요.For more information, see Resource file naming issues section.
  • 클래스 라이브러리의 루트 네임스페이스 변경Changing the root namespace of the class library. 자세한 내용은 루트 네임스페이스 문제 섹션을 참조하세요.For more information, see Root Namespace issues section.

CustomRequestCultureProvider가 예상대로 작동하지 않습니다.CustomRequestCultureProvider doesn't work as expected

RequestLocalizationOptions 클래스에는 세 가지 기본 공급 기업이 포함됩니다.The RequestLocalizationOptions class has three default providers:

  1. QueryStringRequestCultureProvider
  2. CookieRequestCultureProvider
  3. AcceptLanguageHeaderRequestCultureProvider

CustomRequestCultureProvider를 통해 앱에서 지역화 문화권을 제공하는 방법을 사용자 지정할 수 있습니다.The CustomRequestCultureProvider allows you to customize how the localization culture is provided in your app. 기본 공급 기업이 사용자 요구 사항을 충족하지 못할 때 CustomRequestCultureProvider를 사용합니다.The CustomRequestCultureProvider is used when the default providers don't meet your requirements.

  • 사용자 지정 공급 기업이 제대로 작동하지 않는 일반적인 원인은 RequestCultureProviders 목록의 첫 번째 공급 기업이 아니라는 점입니다.A common reason custom provider don't work properly is that it isn't the first provider in the RequestCultureProviders list. 이 문제를 해결하려면:To resolve this issue:

  • 다음과 같이 RequestCultureProviders 목록에서 0의 위치에 있는 사용자 지정 공급 기업을 삽입합니다.Insert the custom provider at the position 0 in the RequestCultureProviders list as the following:

options.RequestCultureProviders.Insert(0, new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return new ProviderCultureResult("en");
    }));
options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return new ProviderCultureResult("en");
    }));
  • AddInitialRequestCultureProvider 확장 메서드를 사용하여 사용자 지정 공급 기업을 초기 공급 기업으로 설정합니다.Use AddInitialRequestCultureProvider extension method to set the custom provider as initial provider.

루트 네임스페이스 문제Root Namespace issues

어셈블리의 루트 네임 스페이스가 어셈블리 이름과 다르면 지역화가 기본적으로 작동하지 않습니다.When the root namespace of an assembly is different than the assembly name, localization doesn't work by default. 이 문제를 방지하려면 여기에 자세히 설명된 대로 RootNamespace를 사용합니다.To avoid this issue use RootNamespace, which is described in detail here

경고

이 오류는 프로젝트 이름이 유효한 .NET 식별자가 아닌 경우 발생할 수 있습니다.This can occur when a project's name is not a valid .NET identifier. 예를 들어 my-project-name.csproj가 루트 네임스페이스 my_project_name과 어셈블리 이름 my-project-name을 사용하면 이 오류가 발생합니다.For instance my-project-name.csproj will use the root namespace my_project_name and the assembly name my-project-name leading to this error.

리소스 및 빌드 작업Resources & Build Action

지역화에 대해 리소스 파일을 사용하는 경우 적절한 빌드 작업이 포함되어야 합니다.If you use resource files for localization, it's important that they have an appropriate build action. 해당 리소스 파일이 포함 리소스여야 하며, 그렇지 않으면 ResourceStringLocalizer가 이러한 리소스를 찾을 수 없습니다.They should be Embedded Resource, otherwise the ResourceStringLocalizer is not able to find these resources.