다음을 통해 공유

지역화된 NuGet 패키지 만들기

라이브러리의 지역화된 버전을 만드는 방법에는 두 가지가 있습니다.

  1. 모든 지역화된 리소스 어셈블리를 단일 패키지에 포함합니다.
  2. 엄격한 규칙 집합에 따라 별도의 지역화된 위성 패키지를 만듭니다.

두 방법 모두 다음 섹션에 설명된 대로 장점과 단점이 있습니다.

단일 패키지의 지역화된 리소스 어셈블리

단일 패키지에 지역화된 리소스 어셈블리를 포함하는 것이 일반적으로 가장 간단한 방법입니다. 이렇게 하려면 패키지 기본값(en-us것으로 가정)이 아닌 지원되는 언어에 대한 폴더를 lib 만듭니다. 이러한 폴더에서 리소스 어셈블리 및 지역화된 IntelliSense XML 파일을 배치할 수 있습니다.

예를 들어 다음 폴더 구조는 독일어(de), 이탈리아어(it), 일본어(ja), 러시아어(ru), 중국어(간체)(zh-Hans) 및 중국어(번체)(zh-Hant)를 지원합니다.

lib
└───net40
    │   Contoso.Utilities.dll
    │   Contoso.Utilities.xml
    │
    ├───de
    │       Contoso.Utilities.resources.dll
    │       Contoso.Utilities.xml
    │
    ├───it
    │       Contoso.Utilities.resources.dll
    │       Contoso.Utilities.xml
    │
    ├───ja
    │       Contoso.Utilities.resources.dll
    │       Contoso.Utilities.xml
    │
    ├───ru
    │       Contoso.Utilities.resources.dll
    │       Contoso.Utilities.xml
    │
    ├───zh-Hans
    │       Contoso.Utilities.resources.dll
    │       Contoso.Utilities.xml
    │
    └───zh-Hant
            Contoso.Utilities.resources.dll
            Contoso.Utilities.xml

언어가 모두 대상 프레임워크 폴더 아래에 net40 나열되어 있음을 확인할 수 있습니다. 여러 프레임워크를 지원하는 경우 각 변형에 대한 폴더가 있습니다lib.

이러한 폴더를 배치하면 해당 시스템에서 모든 파일을 참조할 수 있습니다 .nuspec.

<?xml version="1.0"?>
<package>
    <metadata>...
    </metadata>
    <files>
    <file src="lib\**" target="lib" />
    </files>
</package>

이 방법을 사용하는 한 가지 예제 패키지는 Microsoft.Data.OData 5.4.0입니다.

장점 및 단점(지역화된 리소스 어셈블리)

단일 패키지에서 모든 언어를 번들로 묶는 경우 몇 가지 단점이 있습니다.

  1. 공유 메타데이터: NuGet 패키지는 단일 .nuspec 파일만 포함할 수 있으므로 단일 언어에 대해서만 메타데이터를 제공할 수 있습니다. 즉, NuGet은 지역화된 메타데이터를 지원하지 않습니다.
  2. 패키지 크기: 지원하는 언어 수에 따라 라이브러리가 상당히 커져서 패키지 설치 및 복원 속도가 느려질 수 있습니다.
  3. 동시 릴리스: 지역화된 파일을 단일 패키지로 번들링하려면 각 지역화를 개별적으로 해제하지 않고 해당 패키지의 모든 자산을 동시에 해제해야 합니다. 또한 하나의 지역화를 업데이트하려면 전체 패키지의 새 버전이 필요합니다.

그러나 다음과 같은 몇 가지 이점이 있습니다.

  1. 단순성: 패키지의 소비자는 각 언어를 별도로 설치하지 않고도 지원되는 모든 언어를 단일 설치로 가져옵니다. 또한 nuget.org 단일 패키지를 더 쉽게 찾을 수 있습니다.
  2. 결합된 버전: 모든 리소스 어셈블리는 기본 어셈블리와 동일한 패키지에 있으므로 모두 동일한 버전 번호를 공유하며 잘못 분리될 위험이 없습니다.

지역화된 위성 패키지

.NET Framework에서 위성 어셈블리를 지원하는 방법과 마찬가지로 이 메서드는 지역화된 리소스와 IntelliSense XML 파일을 위성 패키지로 구분합니다.

이렇게 하려면 기본 패키지에서 명명 규칙을 {identifier}.{version}.nupkg 사용하고 기본 언어(예: en-US)에 대한 어셈블리를 포함합니다. 예를 들어 다음 ContosoUtilities.1.0.0.nupkg 구조를 포함합니다.

lib
└───net40
        ContosoUtilities.dll
        ContosoUtilities.xml

위성 어셈블리는 다음과 같은 방식으로 {identifier}.{language}.{version}.nupkg 명명 규칙을, ContosoUtilities.de.1.0.0.nupkg처럼 사용합니다. 식별자는 기본 패키지의 식별자와 정확히 일치 해야 합니다 .

별도의 패키지이므로 지역화된 메타데이터를 포함하는 자체 .nuspec 파일이 있습니다. 해당 언어는 파일 이름에 .nuspec 사용된 언어와 일치해야 합니다.

또한 위성 어셈블리는 [] 버전 표기법을 사용하여 기본 패키지의 정확한 버전을 종속성으로 선언 해야 합니다 ( 패키지 버전 관리 참조). 예를 들어 ContosoUtilities.de.1.0.0.nupkg가 ContosoUtilities.1.0.0.nupkg에 대한 종속성을 [1.0.0] 표기법을 사용하여 선언해야 합니다. 위성 패키지는 물론 기본 패키지와 버전 번호가 다를 수 있습니다.

위성 패키지의 구조는 패키지 파일 이름과 일치하는 {language} 하위 폴더에 리소스 어셈블리 및 XML IntelliSense 파일을 포함해야 합니다.

lib
└───net40
    └───de
            ContosoUtilities.resources.dll
            ContosoUtilities.xml

참고: 필요한 것과 같은 ja-JP 특정 하위 문화권이 없는 한 항상 더 높은 수준의 언어 식별자(예: ja.)를 사용합니다.

위성 어셈블리에서 NuGet은 파일 이름에 일치하는 폴더의 파일{language} 인식합니다. 다른 모든 항목은 무시됩니다.

이러한 모든 규칙이 충족되면 NuGet은 패키지를 위성 패키지로 인식하고 지역화된 파일을 원래 번들로 묶은 것처럼 기본 패키지의 lib 폴더에 설치합니다. 위성 패키지를 제거하면 동일한 폴더에서 해당 파일이 제거됩니다.

지원되는 각 언어에 대해 동일한 방식으로 추가 위성 어셈블리를 만듭니다. 예를 들어 ASP.NET MVC 패키지 집합을 검사합니다.

필수 규칙 요약

  • 기본 패키지의 이름을 지정해야 합니다. {identifier}.{version}.nupkg
  • 위성 패키지의 이름을 지정해야 합니다. {identifier}.{language}.{version}.nupkg
  • 위성 패키지는 .nuspec 파일 이름과 일치하도록 해당 언어를 지정해야 합니다.
  • 위성 패키지는 .nuspec 파일에서 [] 표기법을 사용하여 정확한 주 버전의 종속성을 선언해야 합니다. 범위를 지원하지 않습니다.
  • 위성 패키지는 파일 이름과 정확히 일치하는 lib\[{framework}\]{language} 파일을 {language} 폴더에 배치해야 합니다.

장점 및 단점(위성 패키지)

위성 패키지를 사용하면 다음과 같은 몇 가지 이점이 있습니다.

  1. 패키지 크기: 기본 패키지의 전체 공간을 최소화하고 소비자는 사용하려는 각 언어의 비용만 발생합니다.
  2. 별도의 메타데이터: 각 위성 패키지에는 자체 .nuspec 파일이 있으므로 고유한 지역화된 메타데이터가 있습니다. 이를 통해 일부 소비자는 지역화된 용어로 nuget.org 검색하여 패키지를 더 쉽게 찾을 수 있습니다.
  3. 분리된 릴리스: 위성 어셈블리는 한 번에 모두 릴리스되지 않고 시간이 지남에 따라 릴리스될 수 있으므로 지역화 작업을 분산할 수 있습니다.

그러나 위성 패키지에는 다음과 같은 고유한 단점이 있습니다.

  1. 잡동사니: 단일 패키지 대신 여러 패키지가 있어 nuget.org의 검색 결과를 혼란스럽게 만들고, Visual Studio 프로젝트에서는 긴 참조 목록을 유발할 수 있습니다.
  2. 엄격한 규칙. 위성 패키지는 규칙을 정확하게 따라야 합니다. 그렇지 않으면 지역화된 버전이 제대로 선택되지 않습니다.
  3. 버전 관리: 각 위성 패키지에는 기본 패키지에 대한 정확한 버전 종속성이 있어야 합니다. 즉, 기본 패키지를 업데이트하려면 리소스가 변경되지 않더라도 모든 위성 패키지를 업데이트해야 할 수 있습니다.
  • Last updated on