Yerelleştirilmiş NuGet paketleri oluşturma

  • Makale

Kitaplığın yerelleştirilmiş sürümlerini oluşturmanın iki yolu vardır:

  1. Tüm yerelleştirilmiş kaynak derlemelerini tek bir pakete ekleyin.
  2. Katı bir kural kümesini izleyerek ayrı yerelleştirilmiş uydu paketleri oluşturun.

Aşağıdaki bölümlerde açıklandığı gibi her iki yöntemin de avantajları ve dezavantajları vardır.

Tek bir pakette yerelleştirilmiş kaynak derlemeleri

Yerelleştirilmiş kaynak derlemelerini tek bir pakete dahil olmak genellikle en basit yaklaşımdır. Bunu yapmak için, paket varsayılanı (en-us olduğu varsayılır) dışında desteklenen dil için içinde lib klasörler oluşturun. Bu klasörlerde kaynak derlemelerini ve yerelleştirilmiş IntelliSense XML dosyalarını yerleştirebilirsiniz.

Örneğin, aşağıdaki klasör yapısı Almanca (de), İtalyanca (it), Japonca (ja), Rusça (ru), Çince (Basitleştirilmiş) (zh-Hans) ve Çince (Geleneksel) (zh-Hant) öğesini destekler:

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

Dillerin tümünün hedef çerçeve klasörünün net40 altında listelendiğini görebilirsiniz. Birden çok çerçeveyi destekliyorsanız, her değişken için altında lib bir klasörünüz vardır.

Bu klasörler yerine yerleştirdiğinizde, içindeki tüm dosyalara başvurursunuz .nuspec:

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

Bu yaklaşımı kullanan örnek paketlerden biri Microsoft.Data.OData 5.4.0'dır.

Avantajlar ve dezavantajlar (yerelleştirilmiş kaynak derlemeleri)

Tüm dilleri tek bir pakette paketlemenin birkaç dezavantajı vardır:

  1. Paylaşılan meta veriler: NuGet paketi yalnızca tek .nuspec bir dosya içerebildiğinden, yalnızca tek bir dil için meta veriler sağlayabilirsiniz. Yani, NuGet yerelleştirilmiş meta verileri desteklemez.
  2. Paket boyutu: Desteklediğiniz dil sayısına bağlı olarak, kitaplık önemli ölçüde büyük olabilir ve bu da paketin yüklenmesini ve geri yüklenmesini yavaşlatabilir.
  3. Eşzamanlı sürümler: Yerelleştirilmiş dosyaları tek bir pakette paketlemek, her yerelleştirmeyi ayrı ayrı yayınlamak yerine bu paketteki tüm varlıkları aynı anda serbest bırakmanızı gerektirir. Ayrıca, herhangi bir yerelleştirmede yapılan herhangi bir güncelleştirme paketin tamamının yeni bir sürümünü gerektirir.

Bununla birlikte, birkaç avantajı da vardır:

  1. Basitlik: Paketin tüketicileri desteklenen tüm dilleri ayrı ayrı yüklemek yerine tek bir yüklemede alır. Tek bir paketi de nuget.org daha kolay bulabilirsiniz.
  2. Bağlı sürümler: Tüm kaynak derlemeleri birincil derlemeyle aynı pakette olduğundan, hepsi aynı sürüm numarasını paylaşır ve hatalı bir şekilde ayrıştırma riskiyle karşılaşmazsınız.

Yerelleştirilmiş uydu paketleri

.NET Framework'ün uydu derlemelerini desteklemesine benzer şekilde, bu yöntem yerelleştirilmiş kaynakları ve IntelliSense XML dosyalarını uydu paketlerine ayırır.

Bunu yapmak için birincil paketiniz adlandırma kuralını {identifier}.{version}.nupkg kullanır ve varsayılan dil (en-US gibi) için derlemeyi içerir. Örneğin, ContosoUtilities.1.0.0.nupkg aşağıdaki yapıyı içerir:

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

Uydu derlemesi daha sonra gibi ContosoUtilities.de.1.0.0.nupkgadlandırma kuralını {identifier}.{language}.{version}.nupkgkullanır. Tanımlayıcının birincil paketle tam olarak eşleşmesi gerekir .

Bu ayrı bir paket olduğundan, yerelleştirilmiş meta verileri içeren kendi .nuspec dosyası vardır. içindeki .nuspec dilinin dosya adında kullanılan dille eşleşmesi gerektiğini unutmayın.

Uydu derlemesi ayrıca [] sürüm gösterimini kullanarak birincil paketin tam bir sürümünü bağımlılık olarak bildirmelidir (bkz . Paket sürümü oluşturma). Örneğin, ContosoUtilities.de.1.0.0.nupkg gösterimi kullanma bağımlılığı ContosoUtilities.1.0.0.nupkg bildirmesi [1.0.0] gerekir. Uydu paketi elbette birincil paketten farklı bir sürüm numarasına sahip olabilir.

Uydu paketinin yapısı daha sonra kaynak derlemesini ve XML IntelliSense dosyasını paket dosya adında eşleşen {language} bir alt klasöre içermelidir:

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

Not: gibi ja-JP belirli alt kültürler gerekli değilse, her zaman gibi jadaha yüksek düzeyli dil tanımlayıcısını kullanın.

Bir uydu derlemesinde NuGet, klasördeki dosya adıyla eşleşen {language} dosyaları tanır. Diğer tüm öğeler yoksayılır.

Bu kuralların tümü karşılandığında, NuGet paketi uydu paketi olarak tanır ve yerelleştirilmiş dosyaları birincil paketin lib klasörüne yükler, sanki başlangıçta paketlenmiş gibi. Uydu paketinin kaldırılması, dosyalarını aynı klasörden kaldırır.

Desteklenen her dil için aynı şekilde ek uydu derlemeleri oluşturabilirsiniz. Örneğin, ASP.NET MVC paketleri kümesini inceleyin:

Gerekli kuralların özeti

  • Birincil paket adlandırılmalıdır {identifier}.{version}.nupkg
  • Bir uydu paketi adlandırılmalıdır {identifier}.{language}.{version}.nupkg
  • Bir uydu paketinin .nuspec dosya adıyla eşleşecek dilini belirtmesi gerekir.
  • Bir uydu paketi, dosyasındaki [] gösterimini kullanarak birincil sürümün tam sürümüne .nuspec bağımlılık bildirmelidir. Aralıklar desteklenmez.
  • Uydu paketi, dosya adıyla lib\[{framework}\]{language} tam olarak eşleşen {language} klasöre dosya yerleştirmelidir.

Avantajlar ve dezavantajlar (uydu paketleri)

Uydu paketlerini kullanmanın birkaç avantajı vardır:

  1. Paket boyutu: Birincil paketin genel ayak izi en aza indirilir ve tüketiciler yalnızca kullanmak istedikleri her dilin maliyetlerine tabidir.
  2. Ayrı meta veriler: Her uydu paketinin kendi .nuspec dosyası ve dolayısıyla kendi yerelleştirilmiş meta verileri vardır. Bu, bazı tüketicilerin yerelleştirilmiş terimlerle nuget.org arayarak paketleri daha kolay bulmasını sağlayabilir.
  3. Ayrılmış sürümler: Uydu derlemeleri, yerelleştirme çalışmalarınızı yaymanıza olanak tanıyacak şekilde, zaman içinde bir kerede yayınlanabilir.

Ancak, uydu paketlerinin kendi dezavantajları vardır:

  1. İkincil: Tek bir paket yerine, nuget.org karışık arama sonuçlarına ve Visual Studio projesindeki başvuruların uzun bir listesine yol açabilecek birçok paketiniz vardır.
  2. Katı kurallar. Uydu paketleri kuralları tam olarak izlemelidir, aksi taktirde yerelleştirilmiş sürümler doğru şekilde alınmaz.
  3. Sürüm oluşturma: Her uydu paketinin birincil paket üzerinde tam bir sürüm bağımlılığı olmalıdır. Bu, kaynaklar değişmese bile birincil paketin güncelleştirilmesi için tüm uydu paketlerinin güncelleştirilmesi gerekebileceği anlamına gelir.