ASP.NET Core 앱에서 언어 및 문화권에 대한 지역화된 리소스 제공
참고 항목
이 문서의 최신 버전은 아닙니다. 현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.
Important
이 정보는 상업적으로 출시되기 전에 실질적으로 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적, 또는 묵시적인 보증을 하지 않습니다.
현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.
작성자: Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana 및 Hisham Bin Ateya
앱을 지역화하는 한 가지 작업은 리소스 파일에 지역화된 문자열을 제공하는 것입니다. 이 문서에서는 리소스 파일을 사용하는 방법에 대해 알아봅니다.
SupportedCultures 및 SupportedUICultures
ASP.NET Core에는 문화권 값 SupportedCultures 의 두 컬렉션과 SupportedUICultures. CultureInfo 날짜SupportedCultures, 시간, 숫자 및 통화 서식과 같은 문화권 종속 함수의 결과를 결정하는 개체입니다. SupportedCultures는 또한 텍스트, 대/소문자 규칙 및 문자열 비교의 정렬 순서를 결정합니다. 서버가 문화권을 가져오는 방법에 대한 자세한 내용은 참조 StringComparer.CurrentCulture 하세요. SupportedUICultures는 ResourceManager에서 조회하는 번역된 문자열(.resx 파일에서)을 결정합니다. 단순히 ResourceManager 에 의해 CurrentUICulture결정되는 문화권별 문자열을 조회합니다. .NET의 모든 스레드에는 CurrentCulture 및 CurrentUICulture 개체가 있습니다. ASP.NET Core는 문화권 종속 기능을 렌더링할 때 이러한 값을 검사합니다. 예를 들어 현재 스레드의 문화권이 "en-US"(영어, 미국)로 설정되어 있으면 DateTime.Now.ToLongDateString()은 "Thursday, February 18, 2016"을 표시하지만 CurrentCulture가 "es-ES"(스페인어, 스페인)로 설정되어 있으면 출력은 "jueves, 18 de febrero de 2016"이 됩니다.
리소스 파일
참고: ResX 뷰어 및 편집기 에서는 Visual Studio Code를 사용하여 리소스 파일을 사용하는 대체 메커니즘을 제공합니다.
리소스 파일은 코드에서 지역화 가능한 문자열을 구분하는 데 유용한 메커니즘입니다. 기본이 아닌 언어에 대한 번역된 문자열은 .resx 리소스 파일에서 격리됩니다. 예를 들어 번역된 문자열을 포함하는 Welcome.es.resx라는 스페인어 리소스 파일을 만들 수 있습니다. "es"는 스페인어 언어 코드입니다. Visual Studio에서 이 리소스 파일을 만들려면:
솔루션 탐색기 리소스 파일이 포함될 폴더를 마우스 오른쪽 단추로 클릭한 다음 새 항목 추가>를 선택합니다.
설치된 템플릿 검색 상자에 "리소스"를 입력하고 파일의 이름을 지정합니다.
이름 열에 키 값(네이티브 문자열)을 입력하고 값 열에 번역된 문자열을 입력합니다.
Visual Studio는 Welcome.es.resx 파일을 표시합니다.
리소스 파일 이름 지정
리소스의 이름은 해당 클래스의 전체 형식 이름에서 어셈블리 이름을 빼서 지정됩니다. 예를 들어 주 어셈블리가 LocalizationWebsite.Web.Startup 클래스에 대해 LocalizationWebsite.Web.dll인 프로젝트에서 프랑스어 리소스는 Startup.fr.resx로 이름이 지정됩니다. LocalizationWebsite.Web.Controllers.HomeController 클래스에 대한 리소스는 Controllers.HomeController.fr.resx로 이름이 지정됩니다. 대상 클래스의 네임스페이스가 어셈블리 이름과 동일하지 않은 경우 전체 형식 이름이 필요합니다. 예를 들어 샘플 프로젝트에서 ExtraNamespace.Tools 형식에 대한 리소스는 ExtraNamespace.Tools.fr.resx로 이름이 지정됩니다.
샘플 프로젝트에서 메서드는 ConfigureServices "Resources"로 설정 ResourcesPath 하므로 컨트롤러의 프랑스어 리소스 파일에 대한 home 프로젝트 상대 경로는 Resources/Controllers.HomeController.fr.resx입니다. 또는 폴더를 사용하여 리소스 파일을 구성할 수 있습니다. 컨트롤러의 home 경우 경로 는 Resources/Controllers/HomeController.fr.resx입니다. ResourcesPath 옵션을 사용하지 않는 경우 .resx 파일은 프로젝트 기본 디렉터리로 이동합니다. HomeController에 대한 리소스 파일은 Controllers.HomeController.fr.resx로 이름이 지정됩니다. 점 또는 경로 명명 규칙을 사용하도록 선택하는 것은 리소스 파일을 구성하려는 방법에 따라 다릅니다.
| 리소스 이름 | 점 또는 경로 명명 |
|---|---|
| Resources/Controllers.HomeController.fr.resx | 점 |
| Resources/Controllers/HomeController.fr.resx | Path |
Razor 뷰에서 @inject IViewLocalizer를 사용하는 리소스 파일은 유사한 패턴을 따릅니다. 보기에 대한 리소스 파일은 점 이름 지정 또는 경로 이름 지정을 사용하여 이름이 지정될 수 있습니다. Razor 뷰 리소스 파일은 연결된 보기 파일의 경로를 모방합니다. ResourcesPath를 “Resources”로 설정했다고 가정하면 Views/Home/About.cshtml 보기와 연결된 프랑스어 리소스 파일은 다음 중 하나가 될 수 있습니다.
Resources/Views/Home/About.fr.resx
Resources/Views.Home.About.fr.resx
ResourcesPath 옵션을 사용하지 않는 경우 보기에 대한 .resx 파일은 보기와 동일한 폴더에 위치합니다.
RootNamespaceAttribute
RootNamespaceAttribute 어셈블리의 루트 네임스페이스가 어셈블리 이름과 다른 경우 이 특성은 어셈블리의 루트 네임스페이스를 제공합니다.
Warning
이 오류는 프로젝트 이름이 유효한 .NET 식별자가 아닌 경우 발생할 수 있습니다. 예를 들어 my-project-name.csproj가 루트 네임스페이스 my_project_name과 어셈블리 이름 my-project-name을 사용하면 이 오류가 발생합니다.
어셈블리의 루트 네임 스페이스가 어셈블리 이름과 다른 경우:
- 지역화는 기본적으로 작동하지 않습니다.
- 지역화는 리소스가 어셈블리 내에서 검색되는 방식으로 인해 실패합니다.
RootNamespace는 실행 중인 프로세스에 사용할 수 없는 빌드 시간 값입니다.
RootNamespace가 AssemblyName과 다른 경우, 다음을 AssemblyInfo.cs에 포함합니다(매개 변수 값을 실제 값으로 대체하여 사용).
using System.Reflection;
using Microsoft.Extensions.Localization;
[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]
이전 코드를 사용하면 resx 파일을 해결할 수 있습니다.
문화권 대체 동작
리소스를 검색할 때 지역화는 "문화권 대체"에 참여합니다. 요청된 문화권에서 시작하여 찾을 수 없으면, 해당 문화권의 부모 문화권으로 되돌아갑니다. 이 속성은 CultureInfo.Parent 부모 문화권을 나타냅니다. 이는 일반적으로 언어 및 문화 코드에서 국가 기호를 제거하는 것을 의미합니다. 예를 들어 멕시코에서 사용되는 스페인어는 "es-MX"입니다. 이 문화권의 부모는 "es"로, 특정 국가에 국한되지 않는 스페인어를 말합니다.
사이트가 문화권 "fr-CA"를 사용하여 "시작" 리소스에 대한 요청을 수신한다고 가정해 보겠습니다. 지역화 시스템은 다음 리소스를 순서대로 찾고, 첫 번째 일치 항목을 선택합니다.
- Welcome.fr-CA.resx
- Welcome.fr.resx
- Welcome.resx(
NeutralResourcesLanguage가 "fr-CA"인 경우)
예를 들어 ".fr" 문화권 지정자를 제거하고 프랑스어로 설정된 문화권이 있는 경우 기본 리소스 파일이 읽혀지고 문자열이 지역화됩니다. 리소스 관리자는 요청된 문화권에 맞지 않는 경우에 대한 기본 또는 대체 리소스를 지정합니다. 요청된 문화권에 대한 리소스가 없을 때 키를 반환하려는 경우 기본 리소스 파일이 없어야 합니다.
Visual Studio를 사용하여 리소스 파일 생성
파일 이름에 문화권이 없이(예: Welcome.resx) Visual Studio에서 리소스 파일을 만드는 경우 Visual Studio는 각 문자열에 대한 속성이 있는 C# 클래스를 만듭니다. 일반적으로 이는 사용자가 ASP.NET Core에서 원하는 것은 아닙니다. 일반적으로 기본 .resx 리소스 파일(문화권 이름이 없는 .resx 파일)은 없습니다. 문화권 이름으로 .resx 파일을 만드는 것이 좋습니다(예: Welcome.fr.resx). 문화권 이름으로 .resx 파일을 만드는 경우 Visual Studio는 클래스 파일을 생성하지 않습니다.
다른 문화권 추가
각 언어 및 문화권 조합(기본 언어 이외)에는 고유한 리소스 파일이 필요합니다. 언어 코드가 파일 이름의 일부인 새 리소스 파일(예: en-us, fr-ca 및 en-gb)을 만들어 다양한 문화권 및 로캘에 대한 리소스 파일을 만듭니다. 이러한 코드는 Welcome.es-MX.resx(스페인어/멕시코)와 같이 파일 이름과 .resx 파일 확장명 사이에 배치됩니다.
다음 단계
앱 지역화에는 다음 작업도 포함됩니다.
추가 리소스
- ASP.NET Core에서 미들웨어를 필터로 사용하는 URL 문화권 공급자
- 미들웨어를 필터로 사용하여 RouteDataRequest CultureProvider를 전역적으로 적용
- ASP.NET Core의 세계화 및 지역화
- ASP.NET Core 앱의 콘텐츠를 지역화할 수 있도록 만들기
- 지역화된 ASP.NET Core 앱에서 언어 및 문화권을 선택하기 위한 전략
- ASP.NET Core 지역화 문제 해결
- .NET 애플리케이션 전역화 및 지역화
- Localization.StarterWeb 프로젝트는 문서에서 사용됩니다.
- .resx 파일의 리소스
- Microsoft 다국어 앱 도구 키트
- 지역화 및 제네릭
작성자: Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana 및 Hisham Bin Ateya
앱을 지역화하는 한 가지 작업은 리소스 파일에 지역화된 문자열을 제공하는 것입니다. 이 문서에서는 리소스 파일을 사용하는 방법에 대해 알아봅니다.
SupportedCultures 및 SupportedUICultures
ASP.NET Core에는 문화권 값 SupportedCultures 의 두 컬렉션과 SupportedUICultures. CultureInfo 날짜SupportedCultures, 시간, 숫자 및 통화 서식과 같은 문화권 종속 함수의 결과를 결정하는 개체입니다. SupportedCultures는 또한 텍스트, 대/소문자 규칙 및 문자열 비교의 정렬 순서를 결정합니다. 서버가 문화권을 가져오는 방법에 대한 자세한 내용은 참조 StringComparer.CurrentCulture 하세요. SupportedUICultures는 ResourceManager에서 조회하는 번역된 문자열(.resx 파일에서)을 결정합니다. 단순히 ResourceManager 에 의해 CurrentUICulture결정되는 문화권별 문자열을 조회합니다. .NET의 모든 스레드에는 CurrentCulture 및 CurrentUICulture 개체가 있습니다. ASP.NET Core는 문화권 종속 기능을 렌더링할 때 이러한 값을 검사합니다. 예를 들어 현재 스레드의 문화권이 "en-US"(영어, 미국)로 설정되어 있으면 DateTime.Now.ToLongDateString()은 "Thursday, February 18, 2016"을 표시하지만 CurrentCulture가 "es-ES"(스페인어, 스페인)로 설정되어 있으면 출력은 "jueves, 18 de febrero de 2016"이 됩니다.
리소스 파일
리소스 파일은 코드에서 지역화 가능한 문자열을 구분하는 데 유용한 메커니즘입니다. 기본이 아닌 언어에 대한 번역된 문자열은 .resx 리소스 파일에서 격리됩니다. 예를 들어 번역된 문자열을 포함하는 Welcome.es.resx라는 스페인어 리소스 파일을 만들 수 있습니다. "es"는 스페인어 언어 코드입니다. Visual Studio에서 이 리소스 파일을 만들려면:
솔루션 탐색기 리소스 파일이 포함될 폴더를 마우스 오른쪽 단추로 클릭한 다음 새 항목 추가>를 선택합니다.
설치된 템플릿 검색 상자에 "리소스"를 입력하고 파일의 이름을 지정합니다.
이름 열에 키 값(네이티브 문자열)을 입력하고 값 열에 번역된 문자열을 입력합니다.
Visual Studio는 Welcome.es.resx 파일을 표시합니다.
리소스 파일 이름 지정
리소스의 이름은 해당 클래스의 전체 형식 이름에서 어셈블리 이름을 빼서 지정됩니다. 예를 들어 주 어셈블리가 LocalizationWebsite.Web.Startup 클래스에 대해 LocalizationWebsite.Web.dll인 프로젝트에서 프랑스어 리소스는 Startup.fr.resx로 이름이 지정됩니다. LocalizationWebsite.Web.Controllers.HomeController 클래스에 대한 리소스는 Controllers.HomeController.fr.resx로 이름이 지정됩니다. 대상 클래스의 네임스페이스가 어셈블리 이름과 동일하지 않은 경우 전체 형식 이름이 필요합니다. 예를 들어 샘플 프로젝트에서 ExtraNamespace.Tools 형식에 대한 리소스는 ExtraNamespace.Tools.fr.resx로 이름이 지정됩니다.
샘플 프로젝트에서 메서드는 ConfigureServices "Resources"로 설정 ResourcesPath 하므로 컨트롤러의 프랑스어 리소스 파일에 대한 home 프로젝트 상대 경로는 Resources/Controllers.HomeController.fr.resx입니다. 또는 폴더를 사용하여 리소스 파일을 구성할 수 있습니다. 컨트롤러의 home 경우 경로 는 Resources/Controllers/HomeController.fr.resx입니다. ResourcesPath 옵션을 사용하지 않는 경우 .resx 파일은 프로젝트 기본 디렉터리로 이동합니다. HomeController에 대한 리소스 파일은 Controllers.HomeController.fr.resx로 이름이 지정됩니다. 점 또는 경로 명명 규칙을 사용하도록 선택하는 것은 리소스 파일을 구성하려는 방법에 따라 다릅니다.
| 리소스 이름 | 점 또는 경로 명명 |
|---|---|
| Resources/Controllers.HomeController.fr.resx | 점 |
| Resources/Controllers/HomeController.fr.resx | Path |
Razor 뷰에서 @inject IViewLocalizer를 사용하는 리소스 파일은 유사한 패턴을 따릅니다. 보기에 대한 리소스 파일은 점 이름 지정 또는 경로 이름 지정을 사용하여 이름이 지정될 수 있습니다. Razor 뷰 리소스 파일은 연결된 보기 파일의 경로를 모방합니다. ResourcesPath를 “Resources”로 설정했다고 가정하면 Views/Home/About.cshtml 보기와 연결된 프랑스어 리소스 파일은 다음 중 하나가 될 수 있습니다.
Resources/Views/Home/About.fr.resx
Resources/Views.Home.About.fr.resx
ResourcesPath 옵션을 사용하지 않는 경우 보기에 대한 .resx 파일은 보기와 동일한 폴더에 위치합니다.
RootNamespaceAttribute
RootNamespaceAttribute 어셈블리의 루트 네임스페이스가 어셈블리 이름과 다른 경우 이 특성은 어셈블리의 루트 네임스페이스를 제공합니다.
Warning
이 오류는 프로젝트 이름이 유효한 .NET 식별자가 아닌 경우 발생할 수 있습니다. 예를 들어 my-project-name.csproj가 루트 네임스페이스 my_project_name과 어셈블리 이름 my-project-name을 사용하면 이 오류가 발생합니다.
어셈블리의 루트 네임 스페이스가 어셈블리 이름과 다른 경우:
- 지역화는 기본적으로 작동하지 않습니다.
- 지역화는 리소스가 어셈블리 내에서 검색되는 방식으로 인해 실패합니다.
RootNamespace는 실행 중인 프로세스에 사용할 수 없는 빌드 시간 값입니다.
RootNamespace가 AssemblyName과 다른 경우, 다음을 AssemblyInfo.cs에 포함합니다(매개 변수 값을 실제 값으로 대체하여 사용).
using System.Reflection;
using Microsoft.Extensions.Localization;
[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]
이전 코드를 사용하면 resx 파일을 해결할 수 있습니다.
문화권 대체 동작
리소스를 검색할 때 지역화는 "문화권 대체"에 참여합니다. 요청된 문화권에서 시작하여 찾을 수 없으면, 해당 문화권의 부모 문화권으로 되돌아갑니다. 이 속성은 CultureInfo.Parent 부모 문화권을 나타냅니다. 이는 일반적으로 언어 및 문화 코드에서 국가 기호를 제거하는 것을 의미합니다. 예를 들어 멕시코에서 사용되는 스페인어는 "es-MX"입니다. 이 문화권의 부모는 "es"로, 특정 국가에 국한되지 않는 스페인어를 말합니다.
사이트가 문화권 "fr-CA"를 사용하여 "시작" 리소스에 대한 요청을 수신한다고 가정해 보겠습니다. 지역화 시스템은 다음 리소스를 순서대로 찾고, 첫 번째 일치 항목을 선택합니다.
- Welcome.fr-CA.resx
- Welcome.fr.resx
- Welcome.resx(
NeutralResourcesLanguage가 "fr-CA"인 경우)
예를 들어 ".fr" 문화권 지정자를 제거하고 프랑스어로 설정된 문화권이 있는 경우 기본 리소스 파일이 읽혀지고 문자열이 지역화됩니다. 리소스 관리자는 요청된 문화권에 맞지 않는 경우에 대한 기본 또는 대체 리소스를 지정합니다. 요청된 문화권에 대한 리소스가 없을 때 키를 반환하려는 경우 기본 리소스 파일이 없어야 합니다.
Visual Studio를 사용하여 리소스 파일 생성
파일 이름에 문화권이 없이(예: Welcome.resx) Visual Studio에서 리소스 파일을 만드는 경우 Visual Studio는 각 문자열에 대한 속성이 있는 C# 클래스를 만듭니다. 일반적으로 이는 사용자가 ASP.NET Core에서 원하는 것은 아닙니다. 일반적으로 기본 .resx 리소스 파일(문화권 이름이 없는 .resx 파일)은 없습니다. 문화권 이름으로 .resx 파일을 만드는 것이 좋습니다(예: Welcome.fr.resx). 문화권 이름으로 .resx 파일을 만드는 경우 Visual Studio는 클래스 파일을 생성하지 않습니다.
다른 문화권 추가
각 언어 및 문화권 조합(기본 언어 이외)에는 고유한 리소스 파일이 필요합니다. 언어 코드가 파일 이름의 일부인 새 리소스 파일(예: en-us, fr-ca 및 en-gb)을 만들어 다양한 문화권 및 로캘에 대한 리소스 파일을 만듭니다. 이러한 코드는 Welcome.es-MX.resx(스페인어/멕시코)와 같이 파일 이름과 .resx 파일 확장명 사이에 배치됩니다.
다음 단계
앱 지역화에는 다음 작업도 포함됩니다.
추가 리소스
ASP.NET Core