Kullanıcı arabiriminizdeki ve uygulama paketi bildirimindeki dizeleri yerelleştirme

Windows App SDK uygulamanızı yerelleştirmenin değer teklifi hakkında daha fazla bilgi için bkz. Küreselleştirme ve yerelleştirme.

Uygulamanızın farklı görüntüleme dillerini desteklemesini istiyorsanız ve kodunuzda veya XAML işaretlemenizde veya uygulama paketi bildiriminizde dize değişmez değerleri varsa, bu dizeleri bir Kaynak Dosyası'na (.resw) taşıyın. Ardından uygulamanızın desteklediği her dil için bu Kaynak Dosyasının çevrilmiş bir kopyasını oluşturabilirsiniz.

Sabit dize ifadeleri, imperatif kodda veya XAML işaretlemesinde, örneğin bir TextBlocköğesinin Text özelliği olarak görünebilir. Bunlar, uygulama paketi bildirim kaynak dosyanızda ( Package.appxmanifest dosya), örneğin Visual Studio Bildirim Tasarımcısı'nın Uygulama sekmesinde Görünen ad değeri olarak da görüntülenebilir. Bu dizeleri bir Kaynak Dosyası'na (.resw) taşıyın ve uygulamanızdaki ve bildiriminizdeki sabit kodlanmış dize değişmez değerlerini kaynak tanımlayıcılarına başvurularla değiştirin.

Bir görüntü kaynağı dosyasında yalnızca bir görüntü kaynağı bulunurken, bir dize kaynak dosyasında birden çok dize kaynağı bulunur. Dize kaynak dosyası bir Kaynak Dosyasıdır (.resw) ve genellikle projenizdeki \Strings klasöründe bu tür bir kaynak dosyası oluşturursunuz. Kaynak Dosyalarınızın (.resw) adlarında niteleyicileri kullanma konusunda bilgi için Kaynaklarınızı dil, ölçek ve diğer niteleyiciler için uyarlamabölümüne bakın.

Dizeleri bir kaynak dosyasında depolama

1. Uygulamanızın varsayılan dilini ayarlayın.

   1. Çözümünüz Visual Studio'da açıkken Package.appxmanifest dosyasını açın.
   2. Uygulama sekmesinde, Varsayılan dilin uygun şekilde ayarlandığını onaylayın (örneğin, "en" veya "en-US"). Kalan adımlarda varsayılan dili "en-US" olarak ayarladığınız varsayılır.

   Uyarı

   En azından, bu varsayılan dil için yerelleştirilmiş dize kaynakları sağlamanız gerekir. Bunlar, kullanıcının tercih ettiği dil veya görüntüleme dili ayarları için daha iyi eşleşme bulunamazsa yüklenecek kaynaklardır.

2. Varsayılan dil için bir Kaynak Dosyası (.resw) oluşturun.

   1. Proje düğümünüzün altında yeni bir klasör oluşturun ve adını verin Strings.
   2. altında Stringsyeni bir alt klasör oluşturun ve adını verin en-US.
   3. altında yeni bir Kaynak Dosyası (.resw) oluşturun (Yeni Öğe Ekle iletişim kutusundaki WinUI dosya türlerinin altında ) ve olarak adlandırıldığını onaylayın.

   Uyarı

   Taşımak istediğiniz .NET Kaynak Dosyalarınız (.resx) varsa, XAML ve kullanıcı arabirimi taşıma hakkında daha fazla bilgi için vebölümlerine bakın.

3. Resources.resw Açın ve bu dize kaynaklarını ekleyin.

   Strings/en-US/Resources.resw

   

   Bu örnekte "Selamlama", göstereceğimiz gibi işaretleme dosyanızdan başvurabileceğiniz bir dize kaynak tanımlayıcısıdır. "Greeting" tanımlayıcısı için Text özelliği için bir dize ve Width özelliği için bir dize sağlanır. "Greeting.Text", bir kullanıcı arabirimi öğesinin özelliğine karşılık geldiği için bir özellik tanımlayıcısı örneğidir. Ayrıca, örneğin, Ad sütununa "Greeting.Foreground" ekleyebilir ve Değerini "Kırmızı" olarak ayarlayabilirsiniz. "Veda" tanımlayıcısı basit bir dize kaynak tanımlayıcısıdır; alt özellikleri yoktur ve gösterileceği gibi komut temelli koddan yüklenebilir. Yorum sütunu, çevirmenlere özel yönergeler sağlamak için iyi bir yerdir.

   Bu örnekte, "Farewell" adlı basit bir dize kaynak tanımlayıcısı girişimiz olduğundan, aynı tanımlayıcıyı temel alan özellik tanımlayıcılarına de sahip olamayız. Bu nedenle, Resources.reswoluştururken "Farewell.Text" eklenmesi Yinelenen Girdi hatasına neden olabilir.

   Kaynak tanımlayıcıları büyük/küçük harfe duyarlı değildir ve kaynak dosyası başına benzersiz olmalıdır. Çeviricilere ek bağlam sağlamak için anlamlı kaynak tanımlayıcıları kullandığınızdan emin olun. Ayrıca, dize kaynakları çeviri için gönderildikten sonra kaynak tanımlayıcılarını değiştirmeyin. Yerelleştirme ekipleri kaynak tanımlayıcısını kullanarak kaynaklardaki eklemeleri, silmeleri ve güncelleştirmeleri izler. "Kaynak tanımlayıcıları vardiyası" olarak da bilinen kaynak tanımlayıcılarındaki değişiklikler, dizeler silinmiş ve diğerleri eklenmiş gibi görüneceği için dizelerin yeniden çevrilmesine ihtiyaç duyar.

XAML'den bir dize kaynak tanımlayıcısına başvurma

İşaretlemeyinizdeki bir denetimi veya başka bir öğeyi dize kaynak tanımlayıcısıyla ilişkilendirmek için x:Uid yönergesi kullanırsınız.

<TextBlock x:Uid="Greeting"/>

Çalışma zamanında \Strings\en-US\Resources.resw yüklenir (şu anda projedeki tek Kaynak Dosyası bu olduğundan). TextBlock üzerindeki x:Uid yönergesi, içinde "Greeting" dize kaynak tanımlayıcısını içeren özellik tanımlayıcılarını Resources.resw bulmak için bir aramanın gerçekleşmesine neden olur. "Greeting.Text" ve "Greeting.Width" özellik tanımlayıcıları bulunur ve değerleri, işaretlemede yerel olarak ayarlanan değerleri geçersiz kılarak TextBlock'e uygulanır. Eğer bunu eklemiş olsaydınız, "Greeting.Foreground" değeri de uygulanırdı. Ancak XAML işaretleme öğelerinde özellikleri ayarlamak için yalnızca özellik tanımlayıcıları kullanılır, bu nedenle bu TextBlock üzerinde x:Uid ayarının "Veda" olarak ayarlanmasının hiçbir etkisi olmaz. Resources.resw"Farewell" dize kaynak tanımlayıcısını içerir, ancak bunun için özellik tanımlayıcısı içermez.

XAML öğesine bir dize kaynak tanımlayıcısı atarken, bu tanımlayıcının tüm özellik tanımlayıcılarının XAML öğesi için uygun olduğundan emin olun. Örneğin, x:Uid="Greeting"'i bir TextBlock üzerine ayarlarsanız, TextBlock türünün bir Text özelliği olduğu için "Greeting.Text" çözülecektir. Ancak x:Uid="Greeting"'ı Düğmesi'ye ayarlarsanız, "Greeting.Text" bir çalışma zamanı hatasına neden olur çünkü Düğmesi türünde bir Text özelliği yoktur. Bu durum için çözümlerden biri, "ButtonGreeting.Content" adlı bir özellik tanımlayıcısı yazmak ve x:Uid="ButtonGreeting" ayarlamaktır.

Kaynak dosyasından Genişlik ayarlamak yerine, muhtemelen denetimlerin içeriğe göre dinamik olarak boyutlanmasına izin vermek isteyeceksiniz.

Uyarı

ekli özellikler için bir .resw dosyasının Adı sütununda özel bir söz dizimi gerekir. Örneğin, "Greeting" tanımlayıcısı için eklenen AutomationProperties.Name özelliği için bir değer ayarlamak için Ad sütununa girdiğiniz değer budur.

Greeting.[using:Microsoft.UI.Xaml.Automation]AutomationProperties.Name

Koddan dize kaynak tanımlayıcısına bakın

Basit bir dize kaynak tanımlayıcısı temelinde bir dize kaynağını açıkça yükleyebilirsiniz.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader();
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("Farewell");

Sınıf Kitaplığı projesinin içinden aynı kodu kullanabilirsiniz. Çalışma zamanında, kitaplığı barındıran uygulamanın kaynakları yüklenir. Bir kitaplığın, uygulamayı barındıran uygulamadan kaynakları yüklemesini öneririz, çünkü uygulama daha yüksek bir yerelleştirme derecesine sahip olabilir. Bir kitaplığın kaynak sağlaması gerekiyorsa, barındırma uygulamasına bu kaynakları giriş olarak değiştirme seçeneği vermelidir.

Kaynak adı segmentlere ayrılmışsa ("." karakterleri içeriyorsa), noktaları kaynak adında eğik çizgi ("/") karakterleriyle değiştirin. Özellik tanımlayıcıları, örneğin noktalar içerir; bu nedenle, koddan bunlardan birini yüklemek için bu değişimi yapmanız gerekir.

this.myXAMLTextBlockElement.Text = resourceLoader.GetString("Fare/Well"); // <data name="Fare.Well" ...> ...

Şüpheleriniz varsa, uygulamanızın PRI dosyasını döküm etmek için MakePri.exe kullanabilirsiniz. Her bir kaynağın uri'si dökülen dosyada gösterilir.

<ResourceMapSubtree name="Fare"><NamedResource name="Well" uri="ms-resource://<GUID>/Resources/Fare/Well">...

Uygulama paketi bildiriminizden bir dize kaynak tanımlayıcısına başvurun

1. Uygulama paketi bildirim kaynak dosyanızı (Package.appxmanifest dosyası) açın; burada, uygulamanızın Display name'i varsayılan olarak bir dize sabiti olarak ifade edilir.

   

2. Bu dizenin yerelleştirilebilir bir sürümünü oluşturmak için , "AppDisplayName" adlı ve "Adventure Works Döngüleri" değerine sahip yeni bir dize kaynağı açın Resources.resw ve ekleyin.

3. Görünen ad dizesi değişmez değerini, yeni oluşturduğunuz dize kaynak tanımlayıcısına ("AppDisplayName") bir başvuruyla değiştirin. Bunu yapmak için URI (Tekdüzen Kaynak Tanımlayıcısı) düzenini kullanırsınız ms-resource .

   

4. Bildiriminizdeki yerelleştirmek istediğiniz her dize için bu işlemi yineleyin. Örneğin, uygulamanızın Kısa adı (başlangıç ekranında uygulamanızın kutucuğunda görünecek şekilde yapılandırabilirsiniz). Uygulama paketi bildiriminde yerelleştirebileceğiniz tüm öğelerin listesi için bkz. Yerelleştirilebilir bildirim öğeleri.

Dize kaynaklarını yerelleştirme

1. Başka bir dil için Kaynak Dosyanızın (.resw) bir kopyasını yapın.

   1. "Strings" altında yeni bir alt klasör oluşturun ve Deutsch (Deutschland) için "de-DE" olarak adlandırabilirsiniz.

   Uyarı

   Klasör adı için herhangi bir BCP-47 dil etiketini kullanabilirsiniz. Dil niteleyicisi ve ortak dil etiketleri listesi hakkında ayrıntılı bilgi için bkz. Kaynaklarınızı dil, ölçek ve diğer niteleyiciler için uyarlama . Strings/en-US/Resources.resw dosyasının bir kopyasını Strings/de-DE klasörüne oluşturun.

2. Dizeleri çevirin.

   1. Değer sütunundaki değerleri açın Strings/de-DE/Resources.resw ve çevirin. Açıklamaları çevirmeniz gerekmez.

   Strings/de-DE/Resources.resw

   

İsterseniz, daha fazla dil için 1. ve 2. adımları yineleyebilirsiniz.

Strings/fr-FR/Resources.resw

Uygulamanızı test edin

Uygulamayı varsayılan görüntü diliniz için test edin. Ardından Ayarlar>Saat ve Dil>>Dilleri'nde görüntüleme dilini değiştirebilir ve uygulamanızı yeniden test edebilirsiniz. Kullanıcı arabiriminizdeki ve kabuktaki dizelere bakın (örneğin, ekran adı olarak kullanılan başlık çubuğunuz ve kutucuklarınızdaki Kısa ad).

Uyarı

Görüntüleme dili ayarıyla eşleşen bir klasör adı bulunabiliyorsa, bu klasörün içindeki Kaynaklar Dosyası yüklenir. Aksi takdirde geri dönüş gerçekleşir ve uygulamanızın varsayılan dilinin kaynaklarıyla biter.

Dizeyi birden çok Kaynak Dosyasına ayırma

Tüm dizelerinizi tek bir Kaynak Dosyasında (resw) tutabilir veya bunları birden çok Kaynak Dosyasına dağıtabilirsiniz. Örneğin, hata iletilerinizi bir Kaynak Dosyasında, uygulama paketi bildirim dizelerinizi başka bir dosyada ve kullanıcı arabirimi dizelerinizi üçüncü bir kaynak dosyasında tutmak isteyebilirsiniz. Bu durumda klasör yapınız böyle görünür.

Belirli bir dosyaya bir dize kaynak tanımlayıcısı başvurusunun kapsamını belirlemek için, tanımlayıcıdan önce /<resources-file-name>/ eklemeniz gerekir. Aşağıdaki işaretleme örneğinde adı "PasswordTooWeak.Text" olan ve değeri hatayı açıklayan bir kaynak bulunduğu varsayılır ErrorMessages.resw .

<TextBlock x:Uid="/ErrorMessages/PasswordTooWeak"/>

Yalnızcavedışındaki Kaynak Dosyaları için dize kaynak tanımlayıcısından önce eklemeniz gerekir. Bunun nedeni "Resources.resw" öğesinin varsayılan dosya adı olmasıdır. Bu nedenle, bir dosya adını atlarsanız (bu konudaki önceki örneklerde yaptığımız gibi) bu varsayılır.

Aşağıdaki kod örneğinde adı "MismatchedPasswords" olan ve değeri hatayı açıklayan bir kaynak bulunduğu varsayılır ErrorMessages.resw .

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("ErrorMessages");
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("MismatchedPasswords");

Eğer "AppDisplayName" kaynağınızı Resources.resw'dan ManifestResources.resw'e taşırsanız, uygulama paketi manifestinizde ms-resource:AppDisplayName'yi ms-resource:/ManifestResources/AppDisplayName ile değiştirirsiniz.

Kaynak dosya adı segmentlere ayrılmışsa ("." karakterleri içeriyorsa), başvururken addaki noktaları bırakın. Noktaları, kaynak adlarında olduğu gibi eğik çizgi ("/") karakterleriyle değiştirmeyin.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("Err.Msgs");

Şüpheleriniz varsa, uygulamanızın PRI dosyasını döküm etmek için MakePri.exe kullanabilirsiniz. Her bir kaynağın uri'si dökülen dosyada gösterilir.

<ResourceMapSubtree name="Err.Msgs"><NamedResource name="MismatchedPasswords" uri="ms-resource://<GUID>/Err.Msgs/MismatchedPasswords">...

Belirli bir dil veya başka bir bağlam için dize yükleme

ResourceContext varsayılan (ResourceLoaderoluşturulurken elde edilir), varsayılan çalışma zamanı bağlamını (diğer bir deyişle geçerli kullanıcı ve makinenin ayarları) temsil eden her niteleyici adı için bir niteleyici değeri içerir. Kaynak Dosyaları (.resw), adlarındaki niteleyicilere göre çalışma zamanı bağlamındaki niteleyici değerlerle eşleştirilir.

Ancak, uygulamanızın sistem ayarlarını geçersiz kılmasını ve yüklenecek eşleşen bir Kaynak Dosyası ararken kullanılacak dil, ölçek veya diğer niteleyici değeri hakkında açık olmasını istediğiniz zamanlar olabilir. Örneğin, kullanıcılarınızın araç ipuçları veya hata iletileri için alternatif bir dil seçebilmesini isteyebilirsiniz.

Bunu yapmak için yeni bir ResourceContextoluşturabilir, değerlerini geçersiz kılabilir ve ardından dize aramalarınızda bu bağlam nesnesini kullanabilirsiniz.

var resourceManager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();
var resourceContext = resourceManager.CreateResourceContext();
resourceContext.QualifierValues["Language"] = "de-DE";
var resourceMap = resourceManager.MainResourceMap.GetSubtree("Resources");
this.myXAMLTextBlockElement.Text = resourceMap.GetValue("Farewell", resourceContext).ValueAsString;

Yukarıdaki kod örneğinde olduğu gibi QualifierValues kullanmak herhangi bir niteleyici için işe yarar. Dil'in özel durumu için alternatif olarak bunu yapabilirsiniz.

resourceContext.Languages = new string[] { "de-DE" };

Sınıf Kitaplığı'ndan dizeleri yükleme

Referans alınan sınıf kitaplığının dize kaynakları, genellikle derleme işlemi sırasında dahil edildikleri paketin bir alt klasörüne eklenir. Böyle bir dizenin kaynak tanımlayıcısı genellikle LibraryName/ResourcesFileName/ResourceIdentifier biçimindedir.

Kitaplık kendi kaynakları için resourceloader alabilir. Örneğin, aşağıdaki kod, bir kitaplığın veya ona başvuran bir uygulamanın, kitaplığın dize kaynakları için bir ResourceLoader nasıl edinebileceğini gösterir.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("ContosoControl/Resources");
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("exampleResourceName");

Yol hakkında şüpheleriniz varsa, bileşeninizin veya kitaplığınızın PRI dosyasını dökmek için MakePri.exe komut satırı seçeneklerini belirtebilirsiniz. Her bir kaynağın uri'si dökülen dosyada gösterilir.

<NamedResource name="exampleResourceName" uri="ms-resource://Contoso.Control/Contoso.Control/ReswFileName/exampleResourceName">...

Diğer paketlerden dizeleri yükleme

Bir uygulama paketinin kaynakları, ResourceManagerüzerinden erişilebilen paketin kendi üst düzey ResourceMap'ı aracılığıyla yönetilir ve erişilir. Her pakette, çeşitli bileşenlerin ResourceMap.GetSubtree aracılığıyla erişebileceğiniz kendi ResourceMap alt ağacı olabilir.

Bir çerçeve paketi, mutlak kaynak tanımlayıcısı URI'siyle kendi kaynaklarına erişebilir. Daha fazla bilgi için UWP belgelerindeki URI düzenlerine de bakın.

Paketlenmemiş uygulamalarda dizeleri yükleme

Windows Sürüm 1903 (Mayıs 2019 Güncelleştirmesi) itibarıyla paketlenmemiş uygulamalar da Kaynak Yönetim Sistemi'ni kullanabilir.

Yalnızca Windows Uygulama SDK'sı kullanıcı denetimlerinizi/kitaplıklarınızı oluşturun ve dizeleribir kaynak dosyasında depolayın. Daha sonra XAML bir dize kaynak tanımlayıcısına başvurabilir koddan dize kaynak tanımlayıcısına başvurabilir veyasınıf kitaplığından dizeleri yükleyebilirsiniz.

Paketlenmemiş uygulamalarda kaynakları kullanmak için birkaç şey yapmanız gerekir:

1. Paketlenmemiş senaryolarda varsayılan görünüm olmadığından koddan kaynakları çözümlerken uygulamanızın .pri dosyasının dosya adını geçirmek için ResourceManager aşırı yüklenmiş oluşturucuyu kullanın.
2. Uygulamanızın resources.pri dosyasını el ile oluşturmak için MakePri.exe kullanın.
   • makepri new /pr <PROJECTROOT> /cf <PRICONFIG> /of resources.pri komutunu çalıştırın
   • PRICONFIG<, >tüm kaynakların tek bir resources.pri dosyasında paketlenmesi için "<paketleme>" bölümünü atlamalıdır. createconfig tarafından oluşturulan varsayılan MakePri.exe yapılandırma dosyasını kullanıyorsanız, oluşturulduktan sonra "<paketleme>" bölümünü el ile silmeniz gerekir.
   • PRICONFIG<, >projenizdeki tüm kaynakları tek bir resources.pri dosyasında birleştirmek için gereken tüm ilgili dizin oluşturucuları içermelidir. createconfig tarafından oluşturulan varsayılan MakePri.exe yapılandırma dosyası tüm dizin oluşturucuları içerir.
   • Varsayılan yapılandırmayı kullanmıyorsanız, proje kökünde bulunan proje başvurularından, NuGet başvurularından vb. bulunan PRI'leri birleştirmek için PRI dizin oluşturucusunun etkinleştirildiğinden emin olun (bunun nasıl yapılacağını görmek için varsayılan yapılandırmayı gözden geçirin).

     Uyarı

     çıkartarak ve projenin uygulama manifestosu bulunmadığı için, PRI dosyasının IndexName/kök ad alanı, çalışma zamanının paketsiz uygulamalar için anladığı şekilde otomatik olarak Applicationolarak ayarlanır (bu, önceki paket kimliği üzerindeki sabit bağımlılığı kaldırır). Kaynak URI'lerini belirtirken, kök ad alanını içermeyen ms-resource:/// referansları, paketlenmemiş uygulamalar için kök ad alanı olarak Application varsayar (veya siz, ms-resource://Application/ içinde olduğu gibi, kök ad alanını Application olarak açıkça belirtebilirsiniz).

3. PRI dosyasını .exe derleme çıktı dizinine kopyalayın
4. .exe'yi çalıştır

   Uyarı

   Kaynak Yönetim Sistemi, paketlenmemiş uygulamalarda kaynakları dile göre çözümlerken kullanıcının tercih ettiği dil listesi yerine sistem görüntüleme dilini kullanır. Kullanıcının tercih ettiği dil listesi yalnızca Windows Uygulama SDK'sı paketlenmiş uygulamalar için kullanılır.

Önemli

Kaynaklar değiştirildiğinde PRI dosyalarını el ile yeniden oluşturmanız gerekir. MakePri.exe komutunu işleyen ve resources.pri çıkışını .exe dizinine kopyalayan bir derleme sonrası betik kullanmanızı öneririz.

Önemli API'ler

• ApplicationModel.Resources.ResourceLoader

Ayrıca bakınız

• MRT Core örneği
• Dize kaynaklarını yükleme