Membuat paket NuGet yang dilokalkan

  • Artikel

Ada dua cara untuk membuat versi pustaka yang dilokalkan:

  1. Sertakan semua rakitan sumber daya yang dilokalkan dalam satu paket.
  2. Buat paket satelit terlokalisasi terpisah dengan mengikuti serangkaian konvensi yang ketat.

Kedua metode memiliki kelebihan dan kekurangannya, seperti yang dijelaskan di bagian berikut.

Rakitan sumber daya yang dilokalkan dalam satu paket

Termasuk rakitan sumber daya yang dilokalkan dalam satu paket biasanya merupakan pendekatan paling sederhana. Untuk melakukan ini, buat folder dalam lib bahasa yang didukung selain default paket (diasumsikan en-us). Di folder ini Anda dapat menempatkan rakitan sumber daya dan file XML IntelliSense yang dilokalkan.

Misalnya, struktur folder berikut mendukung, Jerman (de), Italia (it), Jepang (ja), Rusia (ru), Cina (Sederhana) (zh-Hans), dan Cina (Tradisional) (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

Anda dapat melihat bahwa semua bahasa tercantum di bawah net40 folder kerangka kerja target. Jika Anda mendukung beberapa kerangka kerja, maka Anda memiliki folder di bawah lib untuk setiap varian.

Dengan folder ini di tempat, Anda kemudian mereferensikan semua file di :.nuspec

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

Salah satu contoh paket yang menggunakan pendekatan ini adalah Microsoft.Data.OData 5.4.0.

Keuntungan dan kerugian (rakitan sumber daya yang dilokalkan)

Menggabungkan semua bahasa dalam satu paket memiliki beberapa kelemahan:

  1. Metadata bersama: Karena paket NuGet hanya dapat berisi satu .nuspec file, Anda dapat menyediakan metadata hanya untuk satu bahasa. Artinya, NuGet tidak hadir mendukung metadata yang dilokalkan.
  2. Ukuran paket: Tergantung pada jumlah bahasa yang Anda dukung, pustaka dapat menjadi sangat besar, yang memperlambat penginstalan dan pemulihan paket.
  3. Rilis simultan: Menggabungkan file yang dilokalkan ke dalam satu paket mengharuskan Anda merilis semua aset dalam paket tersebut secara bersamaan, daripada dapat merilis setiap pelokalan secara terpisah. Selain itu, pembaruan apa pun untuk satu pelokalan memerlukan versi baru dari seluruh paket.

Namun, ia juga memiliki beberapa manfaat:

  1. Kesederhanaan: Konsumen paket mendapatkan semua bahasa yang didukung dalam satu instalasi, daripada harus menginstal setiap bahasa secara terpisah. Satu paket juga lebih mudah ditemukan di nuget.org.
  2. Versi yang digabungkan: Karena semua rakitan sumber daya berada dalam paket yang sama dengan rakitan utama, semuanya memiliki nomor versi yang sama dan tidak berisiko dipisahkan secara keliru.

Paket satelit yang dilokalkan

Mirip dengan cara .NET Framework mendukung rakitan satelit, metode ini memisahkan sumber daya yang dilokalkan dan file XML IntelliSense ke dalam paket satelit.

Lakukan hal ini, paket utama Anda menggunakan konvensi {identifier}.{version}.nupkg penamaan dan berisi perakitan untuk bahasa default (seperti en-US). Misalnya, ContosoUtilities.1.0.0.nupkg akan berisi struktur berikut:

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

Rakitan satelit kemudian menggunakan konvensi {identifier}.{language}.{version}.nupkgpenamaan , seperti ContosoUtilities.de.1.0.0.nupkg. Pengidentifikasi harus sama persis dengan paket utama.

Karena ini adalah paket terpisah, ini memiliki file sendiri .nuspec yang berisi metadata yang dilokalkan. Perhatikan bahwa bahasa dalam .nuspecharus cocok dengan yang digunakan dalam nama file.

Rakitan satelit juga harus mendeklarasikan versi yang tepat dari paket utama sebagai dependensi, menggunakan notasi versi [] (lihat Penerapan versi paket). Misalnya, ContosoUtilities.de.1.0.0.nupkg harus mendeklarasikan dependensi pada ContosoUtilities.1.0.0.nupkg penggunaan [1.0.0] notasi. Paket satelit tentu saja dapat memiliki nomor versi yang berbeda dari paket utama.

Struktur paket satelit kemudian harus menyertakan assembly sumber daya dan file XML IntelliSense dalam subfolder yang cocok {language} dalam nama file paket:

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

Catatan: kecuali subkultur tertentu seperti ja-JP diperlukan, selalu gunakan pengidentifikasi bahasa tingkat yang lebih tinggi, seperti ja.

Dalam rakitan satelit, NuGet hanya akan mengenali file-file tersebut di folder yang cocok dengan {language} dalam nama file. Yang lain diabaikan.

Ketika semua konvensi ini terpenuhi, NuGet akan mengenali paket sebagai paket satelit dan menginstal file yang dilokalkan ke folder paket lib utama, seolah-olah mereka awalnya dibundel. Menghapus instalan paket satelit akan menghapus filenya dari folder yang sama.

Anda akan membuat rakitan satelit tambahan dengan cara yang sama untuk setiap bahasa yang didukung. Misalnya, periksa set paket MVC ASP.NET:

Ringkasan konvensi yang diperlukan

  • Paket primer harus diberi nama {identifier}.{version}.nupkg
  • Paket satelit harus diberi nama {identifier}.{language}.{version}.nupkg
  • Paket .nuspec satelit harus menentukan bahasanya agar sesuai dengan nama file.
  • Paket satelit harus mendeklarasikan dependensi pada versi yang tepat dari primer menggunakan notasi [] dalam filenya .nuspec . Rentang tidak didukung.
  • Paket satelit harus menempatkan file di lib\[{framework}\]{language} folder yang sama persis {language} dengan nama file.

Kelebihan dan kekurangan (paket satelit)

Menggunakan paket satelit memiliki beberapa manfaat:

  1. Ukuran paket: Jejak keseluruhan paket utama diminimalkan, dan konsumen hanya dikenakan biaya setiap bahasa yang ingin mereka gunakan.
  2. Metadata terpisah: Setiap paket satelit memiliki filenya sendiri .nuspec dan dengan demikian metadata terlokalisasinya sendiri. Ini dapat memungkinkan beberapa konsumen untuk menemukan paket dengan lebih mudah dengan mencari nuget.org dengan istilah yang dilokalkan.
  3. Rilis yang dipisahkan: Rakitan satelit dapat dirilis dari waktu ke waktu, bukan sekaligus, memungkinkan Anda untuk menyebarkan upaya pelokalan Anda.

Namun, paket satelit memiliki serangkaian kelemahannya sendiri:

  1. Clutter: Alih-alih satu paket, Anda memiliki banyak paket yang dapat menyebabkan hasil pencarian yang berantakan pada nuget.org dan daftar panjang referensi dalam proyek Visual Studio.
  2. Konvensi ketat. Paket satelit harus mengikuti konvensi dengan tepat atau versi yang dilokalkan tidak akan diambil dengan benar.
  3. Penerapan versi: Setiap paket satelit harus memiliki dependensi versi yang tepat pada paket utama. Ini berarti bahwa memperbarui paket utama mungkin juga memerlukan pembaruan semua paket satelit, bahkan jika sumber daya tidak berubah.