Kualifikasi di MRM

Pengindeks Sumber Daya (dan runtime MRT) menggunakan "kualifikasi" untuk menentukan konteks di mana kandidat sumber daya tertentu harus digunakan. Setiap sumber daya memiliki nama dan satu atau beberapa kandidat (atau nilai), dan setiap kandidat memiliki nol atau lebih kualifikasi. Untuk informasi selengkapnya tentang penamaan sumber daya, lihat Nama sumber daya di MRM.

Misalnya, mungkin ada sumber daya string bernama salam dengan tiga kandidat berbeda untuk tiga pelokalan yang berbeda:

  • Untuk bahasa Inggris, teks "Halo"
  • Untuk bahasa Jerman, teks "Hallo"
  • Untuk bahasa Korea, teks "안녕하세요"

Kandidat ini ditambahkan ke Pengindeks dengan kualifikasi bahasa yang benar, dan ini disimpan dalam file PRI sehingga MRT tahu mana yang akan digunakan saat runtime. Misalnya, untuk menambahkan ketiga string ini ke pengindeks yang mungkin menggunakan:

    HRESULT hr{};
    hr = MrmIndexString(indexer, L"ms-resource:///strings/greeting", L"Hello", L"language-en");
    hr |= MrmIndexString(indexer, L"ms-resource:///strings/greeting", L"Hallo", L"language-de");
    hr |= MrmIndexString(indexer, L"ms-resource:///strings/greeting", L"안녕하세요", L"language-ko");
    if (FAILED(hr)) { /* error handling */ }

Bahasa hanyalah salah satu kualifikasi yang mungkin; kualifikasi umum lainnya termasuk Skala (untuk menentukan gambar pada resolusi yang berbeda) atau Kontras (untuk pengaturan kontras yang berbeda). Daftar lengkap kualifikasi tercantum dalam topik ResourceContext.QualifierValues.

Perhatikan bahwa bentuk "pendek" dari kualifikasi (misalnya "bahasa" alih-alih "bahasa") tidak didukung oleh API MRM; Anda harus menggunakan bentuk panjang. Namun demikian, fungsi MrmIndexFileAutoQualifiers dan MrmIndexResourceContainerAutoQualifiers yang menyimpulkan kualifikasi dari jalur file mendukung bentuk pendek.

Kualifikasi ditentukan sebagai string dalam formulir name-value, seperti language-en atau scale-200. (Nilai untuk Kualifikasi bahasa juga dapat berisi tanda hubung, seperti en-us.) Nama dan nilainya tidak peka huruf besar/kecil, jadi LANGUAGE-EN-US, Language-En-Us, dan language-en-us semuanya setara.

Perhatikan bahwa ini adalah kesalahan untuk menentukan dua kandidat untuk sumber daya yang sama dengan kualifikasi yang sama tetapi nilai yang berbeda. Sayangnya, kesalahan ini tidak muncul ketika sumber daya ditambahkan ke pengindeks (misalnya saat memanggil MrmIndexString) tetapi pada saat file PRI dihasilkan - pembuatan akan mengembalikan ERROR_MRM_DUPLICATE_ENTRY tetapi tidak memberikan indikasi sumber daya mana yang menyebabkan masalah.

Misalnya, cuplikan kode ini akan berhasil saat menambahkan kandidat duplikat, tetapi gagal nanti selama pembuatan PRI:

// Add "color = red". Returns S_OK, since all arguments are valid.
hr = MrmIndexString(indexer, L"ms-resource:///strings/color", L"red", L"language-en"); 
// Add "color = blue". Returns S_OK, since all arguments are valid (in isolation).
hr = MrmIndexString(indexer, L"ms-resource:///strings/color", L"blue", L"language-en"); 

// Fails with ERROR_MRM_DUPLICATE_ENTRY since there are two English candidates for "strings/color" 
// ("red" and "blue"). 
hr = MrmCreateResourceFile(indexer, MrmPackagingModeStandaloneFile, MrmPackagingOptionsNone, fileName);

Jika kandidat yang sama persis ditambahkan dua kali (misalnya dalam kode di atas, jika panggilan kedua mengulangi "merah" alih-alih menggunakan "biru") maka duplikat diabaikan dan tidak ada kesalahan yang dihasilkan.

Daftar kualifikasi

Kandidat sumber daya dapat memiliki lebih dari satu kualifikasi. Misalnya, file gambar mungkin memerlukan kandidat berdasarkan Skala (100%, 200%, dll.) dan Kontras (standar atau tinggi). Jika gambar berisi teks, gambar mungkin juga perlu memenuhi syarat berdasarkan Bahasa.

Beberapa kualifikasi ditentukan dalam satu string, dipisahkan oleh garis bawah. Misalnya, kandidat gambar untuk kontras tinggi pada skala 200% akan menggunakan kualifikasi contrast-high_scale-200. Urutan di mana kualifikasi ditentukan dalam daftar tidak masalah; MRT memiliki urutan kepentingan bawaan untuk setiap kualifikasi (misalnya Bahasa lebih penting daripada Skala).

Meskipun bukan kesalahan untuk mengulangi kualifikasi dalam daftar kualifikasi (bahkan dengan nilai yang berbeda), semua kecuali yang pertama akan diabaikan.

  • language-en_language-en (tentukan bahasa Inggris dua kali - bahasa yang efektif adalah bahasa Inggris)
  • language-en_language-de (tentukan bahasa Inggris maka Jerman - bahasa yang efektif adalah bahasa Inggris)
  • language-de_language-en (tentukan bahasa Jerman maka Bahasa Inggris - bahasa yang efektif adalah Bahasa Jerman)

Seperti disebutkan di atas, ini adalah kesalahan untuk menambahkan dua kandidat sumber daya dengan kualifikasi yang sama tetapi nilai yang berbeda. Ini terlepas dari urutan kualifikasi dalam daftar kualifikasi.

Kandidat netral

Saat menambahkan kandidat sumber daya ke pengindeks, Anda dapat menentukan string kosong (atau penunjuk null) sebagai kualifikasi untuk menunjukkan bahwa kandidat "netral" dan dapat mencocokkan konteks apa pun. Misalnya, nama aplikasi yang ditampilkan di menu Mulai mungkin kandidat netral karena nama aplikasi biasanya tidak dilokalkan (dan tidak bergantung pada hal-hal lain seperti Skala atau Kontras). Kandidat netral dapat digunakan selain kandidat tertentu, jika diinginkan.

Contohnya:

// The name of the app is the same, regardless of language, scale, etc.
hr = MrmIndexString(indexer, L"ms-resource:///strings/AppName", L"Contoso Widgets", nullptr); 

// The name of the publisher is always "Contoso Inc." except in Australia, where it is "Contoso PTY LTD".
hr = MrmIndexString(indexer, L"ms-resource:///strings/AppPublisher", L"Contoso Inc.", nullptr); 
hr = MrmIndexString(indexer, L"ms-resource:///strings/AppPublisher", L"Contoso PTY LTD", L"homeregion-au");

Kualifikasi Default

Saat membuat file konfigurasi (melalui salah satu fungsi MrmCreateConfig... ) atau membuat Pengindeks Sumber Daya (melalui salah satu fungsi MrmCreateResourceIndexer... ) DefaultQualifier adalah kualifikasi (seperti bahasa) yang menunjukkan kandidat sumber daya yang akan digunakan jika tidak ada kecocokan yang lebih baik yang dapat ditemukan. Misalnya, jika aplikasi memiliki sumber daya dalam bahasa Inggris dan Prancis, tetapi berjalan pada sistem dengan bahasa yang diatur ke Bahasa Jepang, bahasa yang ditentukan sebagai "kualifikasi default" ketika file PRI dibuat akan digunakan. Kualifikasi default juga menentukan bahasa dan skala mana yang harus digunakan untuk membuat file PRI utama saat menggunakan kemasan AutoSplit (lihat MrmPackagingMode untuk informasi selengkapnya).

Perhatikan bahwa semua sumber daya harus memiliki kandidat yang ditentukan dengan kualifikasi default (atau kandidat netral), jika tidak, tidak akan ada yang bisa dijatuhkan kembali jika tidak ada kecocokan terbaik. Perhatikan bahwa gagal memberikan kandidat fallback tidak dianggap sebagai kesalahan (pengindeks akan menghasilkan kandidat string kosong untuk Anda) tetapi dapat mengakibatkan pengalaman pengguna yang buruk atau bug aplikasi.

  • Last updated on