ASP.NET Core uygulamasında diller ve kültürler için yerelleştirilmiş kaynaklar sağlama
Uyarı
ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.
Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana ve Hisham Bin Ateya
Bir uygulamayı yerelleştirmeye yönelik bir görev, kaynak dosyalarında yerelleştirilmiş dizeler sağlamaktır. Bu makale, kaynak dosyalarıyla çalışma hakkındadır.
SupportedCultures
ve SupportedUICultures
ASP.NET Core'un iki kültür değeri SupportedCultures
koleksiyonu vardır ve SupportedUICultures
. CultureInfo nesnesi SupportedCultures
tarih, saat, sayı ve para birimi biçimlendirmesi gibi kültüre bağımlı işlevlerin sonuçlarını belirler. SupportedCultures
ayrıca metnin sıralama düzenini, büyük/küçük harf kurallarını ve dize karşılaştırmalarını belirler. Sunucunun kültürü nasıl aldığı hakkında daha fazla bilgi için bkz StringComparer.CurrentCulture . , SupportedUICultures
hangi çevrilmiş dizelerin (.resx dosyalarından) tarafından ResourceManagerarandığını belirler. yalnızca ResourceManager
tarafından CurrentUICulture
belirlenen kültüre özgü dizeleri arar. .NET'teki her iş parçacığında ve CurrentUICulture
nesneleri vardırCurrentCulture
. ASP.NET Core, kültüre bağımlı işlevleri işlerken bu değerleri inceler. Örneğin, geçerli iş parçacığının kültürü "en-US" (İngilizce, Birleşik Devletler) DateTime.Now.ToLongDateString()
olarak ayarlandıysa, "Perşembe, 18 Şubat 2016" değerini görüntüler, ancak "es-ES" (İspanyolca, İspanya) olarak ayarlanırsa CurrentCulture
çıkış "jueves, 18 de febrero de 2016" olur.
Kaynak dosyalar
NOT: ResX Görüntüleyicisi ve Düzenleyici , Visual Studio Code kullanarak kaynak dosyalarıyla çalışmak için alternatif bir mekanizma sağlar.
Kaynak dosyası, yerelleştirilebilir dizeleri koddan ayırmak için kullanışlı bir mekanizmadır. Varsayılan olmayan dil için çevrilmiş dizeler .resx kaynak dosyalarında yalıtılır. Örneğin, çevrilmiş dizeler içeren Welcome.es.resx adlı bir İspanyolca kaynak dosyası oluşturmak isteyebilirsiniz. "es", İspanyolca için dil kodudur. Visual Studio'da bu kaynak dosyasını oluşturmak için:
Çözüm Gezgini kaynak dosyasını içeren klasöre sağ tıklayın ve ardından Yeni Öğe Ekle'yi>seçin.
Yüklü şablonları ara kutusuna "kaynak" yazın ve dosyayı adlandırın.
Ad sütununa anahtar değerini (yerel dize) ve Değer sütununa çevrilmiş dizeyi girin.
Visual Studio Welcome.es.resx dosyasını gösterir.
Kaynak dosya adlandırma
Kaynaklar, sınıflarının tam tür adı için, derleme adı çıkarıldığında adlandırılır. Örneğin, ana derlemesi LocalizationWebsite.Web.dll
sınıfı LocalizationWebsite.Web.Startup
için olan bir projedeki Fransızca kaynağı Startup.fr.resx olarak adlandırılır. Sınıfın LocalizationWebsite.Web.Controllers.HomeController
kaynağı Controllers.HomeController.fr.resx olarak adlandırılır. Hedeflenen sınıfınızın ad alanı derleme adıyla aynı değilse tam tür adı gerekir. Örneğin, örnek projede türü ExtraNamespace.Tools
için bir kaynak ExtraNamespace.Tools.fr.resx olarak adlandırılabilir.
Örnek projede ConfigureServices
yöntemi öğesini "Resources" olarak ayarlarResourcesPath
; dolayısıyla denetleyicinin Fransızca kaynak dosyasının home proje göreli yolu Resources/Controllers.HomeController.fr.resx şeklindedir. Alternatif olarak, kaynak dosyalarını düzenlemek için klasörleri kullanabilirsiniz. Denetleyici için home yol Resources/Controllers/HomeController.fr.resx olabilir. seçeneğini kullanmazsanız ResourcesPath
, .resx dosyası proje temel dizinine gider. için HomeController
kaynak dosyası Controllers.HomeController.fr.resx olarak adlandırılır. Nokta veya yol adlandırma kuralını kullanma seçimi, kaynak dosyalarınızı nasıl düzenlemek istediğinize bağlıdır.
Kaynak adı | Nokta veya yol adlandırma |
---|---|
Resources/Controllers.HomeController.fr.resx | Nokta |
Kaynaklar/Denetleyiciler/HomeController.fr.resx | Yol |
Görünümlerde Razor kullanan @inject IViewLocalizer
kaynak dosyaları benzer bir desene uyar. Bir görünümün kaynak dosyası nokta adlandırma veya yol adlandırma kullanılarak adlandırılabilir. Razor kaynak dosyalarını görüntüleme, ilişkili görünüm dosyalarının yolunu taklit etme. "Kaynaklar" olarak ayarladığımız ResourcesPath
varsayıldığında, görünümle Views/Home/About.cshtml
ilişkili Fransız kaynak dosyası aşağıdakilerden biri olabilir:
Kaynaklar/Görünümler/Home/About.fr.resx
Kaynaklar/Görünümler.Home. About.fr.resx
seçeneğini kullanmazsanız ResourcesPath
, bir görünümün .resx dosyası görünümle aynı klasörde yer alır.
RootNamespaceAttribute
özniteliği, RootNamespaceAttribute bir derlemenin kök ad alanı derleme adından farklı olduğunda derlemenin kök ad alanını sağlar.
Uyarı
Projenin adı geçerli bir .NET tanımlayıcısı olmadığında bu durum oluşabilir. Örneğin my-project-name.csproj
, kök ad alanını my_project_name
ve bu hataya yol açan derleme adını my-project-name
kullanır.
Bir derlemenin kök ad alanı derleme adından farklıysa:
- Yerelleştirme varsayılan olarak çalışmaz.
- Yerelleştirme, kaynakların derleme içinde aranma şeklinden dolayı başarısız oluyor.
RootNamespace
, yürütme işlemi tarafından kullanılamayan bir derleme zamanı değeridir.
RootNamespace
dosyasından AssemblyName
farklıysa, aşağıdakini ekleyin AssemblyInfo.cs
(parametre değerleri gerçek değerlerle değiştirilir):
using System.Reflection;
using Microsoft.Extensions.Localization;
[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]
Yukarıdaki kod, resx dosyalarının başarılı bir şekilde çözümlenmesine olanak tanır.
Kültür geri dönüş davranışı
Bir kaynağı ararken, yerelleştirme "kültür geri dönüşü" ile etkileşim kurar. İstenen kültürden başlayarak, bulunamazsa, bu kültürün üst kültürüne geri döner. Bir yana, CultureInfo.Parent özelliği üst kültürü temsil eder. Bu genellikle (ancak her zaman değil), ulusal işaretleyiciyi dil ve kültür kodundan kaldırma anlamına gelir. Örneğin, Meksika'da İspanyolca konuşulan diyalekt "es-MX" şeklindedir. Üst "es" (herhangi bir ülkeye özgü olmayan İspanyolca) vardır.
Sitenizin "fr-CA" kültürünü kullanarak bir "Hoş Geldiniz" kaynağı isteği aldığını düşünün. Yerelleştirme sistemi sırayla aşağıdaki kaynakları arar ve ilk eşleşmeyi seçer:
- Welcome.fr-CA.resx
- Welcome.fr.resx
- Welcome.resx ("fr-CA" ise
NeutralResourcesLanguage
)
Örneğin, ".fr" kültür belirleyicisini kaldırırsanız ve kültür Fransızca olarak ayarlanırsa, varsayılan kaynak dosyası okunur ve dizeler yerelleştirilir. Resource manager, istenen kültürünüzü hiçbir şey karşılamadığında için varsayılan veya geri dönüş kaynağı belirtir. İstenen kültür için bir kaynak eksikken anahtarı döndürmek istiyorsanız, varsayılan kaynak dosyanız olmamalıdır.
Visual Studio ile kaynak dosyaları oluşturma
Visual Studio'da dosya adında bir kültür olmadan bir kaynak dosyası oluşturursanız (örneğin, Welcome.resx), Visual Studio her dize için bir özelliği olan bir C# sınıfı oluşturur. Genellikle ASP.NET Core'da istediğiniz bu değildir. Normalde varsayılan bir .resx kaynak dosyanız (kültür adı olmayan bir .resx dosyası) yoktur. .resx dosyasını bir kültür adıyla (örneğin Welcome.fr.resx) oluşturmanızı öneririz. Kültür adıyla bir .resx dosyası oluşturduğunuzda, Visual Studio sınıf dosyasını oluşturmaz.
Diğer kültürleri ekleme
Her dil ve kültür bileşimi (varsayılan dil dışında) benzersiz bir kaynak dosyası gerektirir. Dil kodlarının dosya adının bir parçası olduğu yeni kaynak dosyaları (örneğin, en-us, fr-ca ve en-gb) oluşturarak farklı kültürler ve yerel ayarlar için kaynak dosyaları oluşturursunuz. Bu kodlar, Welcome.es-MX.resx (İspanyolca/Meksika) içinde olduğu gibi dosya adı ile .resx dosya uzantısı arasına yerleştirilir.
Sonraki adımlar
Bir uygulamayı yerelleştirmek aşağıdaki görevleri de içerir:
- Uygulamanın içeriğini yerelleştirilebilir hale getirin.
- Her istek için dil/kültür seçmek için bir strateji uygulama
Ek kaynaklar
- ASP.NET Core'da ara yazılımı filtre olarak kullanan URL kültürü sağlayıcısı
- RouteDataRequest CultureProvider'i genel olarak ara yazılımla filtre olarak uygulama
- ASP.NET Core'da genelleştirme ve yerelleştirme
- ASP.NET Core uygulamasının içeriğini yerelleştirilebilir hale getirme
- Yerelleştirilmiş ASP.NET Core uygulamasında dil ve kültür seçme stratejileri
- ASP.NET Çekirdek yerelleştirme sorunlarını giderme
- .NET uygulamalarını genelleştirme ve yerelleştirme
- Makalede kullanılan Localization.StarterWeb projesi .
- .resx Dosyalarındaki Kaynaklar
- Microsoft Çok Dilli Uygulama Araç Seti
- Yerelleştirme ve Genel Değerler
Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana ve Hisham Bin Ateya
Bir uygulamayı yerelleştirmeye yönelik bir görev, kaynak dosyalarında yerelleştirilmiş dizeler sağlamaktır. Bu makale, kaynak dosyalarıyla çalışma hakkındadır.
SupportedCultures
ve SupportedUICultures
ASP.NET Core'un iki kültür değeri SupportedCultures
koleksiyonu vardır ve SupportedUICultures
. CultureInfo nesnesi SupportedCultures
tarih, saat, sayı ve para birimi biçimlendirmesi gibi kültüre bağımlı işlevlerin sonuçlarını belirler. SupportedCultures
ayrıca metnin sıralama düzenini, büyük/küçük harf kurallarını ve dize karşılaştırmalarını belirler. Sunucunun kültürü nasıl aldığı hakkında daha fazla bilgi için bkz StringComparer.CurrentCulture . , SupportedUICultures
hangi çevrilmiş dizelerin (.resx dosyalarından) tarafından ResourceManagerarandığını belirler. yalnızca ResourceManager
tarafından CurrentUICulture
belirlenen kültüre özgü dizeleri arar. .NET'teki her iş parçacığında ve CurrentUICulture
nesneleri vardırCurrentCulture
. ASP.NET Core, kültüre bağımlı işlevleri işlerken bu değerleri inceler. Örneğin, geçerli iş parçacığının kültürü "en-US" (İngilizce, Birleşik Devletler) DateTime.Now.ToLongDateString()
olarak ayarlandıysa, "Perşembe, 18 Şubat 2016" değerini görüntüler, ancak "es-ES" (İspanyolca, İspanya) olarak ayarlanırsa CurrentCulture
çıkış "jueves, 18 de febrero de 2016" olur.
Kaynak dosyalar
Kaynak dosyası, yerelleştirilebilir dizeleri koddan ayırmak için kullanışlı bir mekanizmadır. Varsayılan olmayan dil için çevrilmiş dizeler .resx kaynak dosyalarında yalıtılır. Örneğin, çevrilmiş dizeler içeren Welcome.es.resx adlı bir İspanyolca kaynak dosyası oluşturmak isteyebilirsiniz. "es", İspanyolca için dil kodudur. Visual Studio'da bu kaynak dosyasını oluşturmak için:
Çözüm Gezgini kaynak dosyasını içeren klasöre sağ tıklayın ve ardından Yeni Öğe Ekle'yi>seçin.
Yüklü şablonları ara kutusuna "kaynak" yazın ve dosyayı adlandırın.
Ad sütununa anahtar değerini (yerel dize) ve Değer sütununa çevrilmiş dizeyi girin.
Visual Studio Welcome.es.resx dosyasını gösterir.
Kaynak dosya adlandırma
Kaynaklar, sınıflarının tam tür adı için, derleme adı çıkarıldığında adlandırılır. Örneğin, ana derlemesi LocalizationWebsite.Web.dll
sınıfı LocalizationWebsite.Web.Startup
için olan bir projedeki Fransızca kaynağı Startup.fr.resx olarak adlandırılır. Sınıfın LocalizationWebsite.Web.Controllers.HomeController
kaynağı Controllers.HomeController.fr.resx olarak adlandırılır. Hedeflenen sınıfınızın ad alanı derleme adıyla aynı değilse tam tür adı gerekir. Örneğin, örnek projede türü ExtraNamespace.Tools
için bir kaynak ExtraNamespace.Tools.fr.resx olarak adlandırılabilir.
Örnek projede ConfigureServices
yöntemi öğesini "Resources" olarak ayarlarResourcesPath
; dolayısıyla denetleyicinin Fransızca kaynak dosyasının home proje göreli yolu Resources/Controllers.HomeController.fr.resx şeklindedir. Alternatif olarak, kaynak dosyalarını düzenlemek için klasörleri kullanabilirsiniz. Denetleyici için home yol Resources/Controllers/HomeController.fr.resx olabilir. seçeneğini kullanmazsanız ResourcesPath
, .resx dosyası proje temel dizinine gider. için HomeController
kaynak dosyası Controllers.HomeController.fr.resx olarak adlandırılır. Nokta veya yol adlandırma kuralını kullanma seçimi, kaynak dosyalarınızı nasıl düzenlemek istediğinize bağlıdır.
Kaynak adı | Nokta veya yol adlandırma |
---|---|
Resources/Controllers.HomeController.fr.resx | Nokta |
Kaynaklar/Denetleyiciler/HomeController.fr.resx | Yol |
Görünümlerde Razor kullanan @inject IViewLocalizer
kaynak dosyaları benzer bir desene uyar. Bir görünümün kaynak dosyası nokta adlandırma veya yol adlandırma kullanılarak adlandırılabilir. Razor kaynak dosyalarını görüntüleme, ilişkili görünüm dosyalarının yolunu taklit etme. "Kaynaklar" olarak ayarladığımız ResourcesPath
varsayıldığında, görünümle Views/Home/About.cshtml
ilişkili Fransız kaynak dosyası aşağıdakilerden biri olabilir:
Kaynaklar/Görünümler/Home/About.fr.resx
Kaynaklar/Görünümler.Home. About.fr.resx
seçeneğini kullanmazsanız ResourcesPath
, bir görünümün .resx dosyası görünümle aynı klasörde yer alır.
RootNamespaceAttribute
özniteliği, RootNamespaceAttribute bir derlemenin kök ad alanı derleme adından farklı olduğunda derlemenin kök ad alanını sağlar.
Uyarı
Projenin adı geçerli bir .NET tanımlayıcısı olmadığında bu durum oluşabilir. Örneğin my-project-name.csproj
, kök ad alanını my_project_name
ve bu hataya yol açan derleme adını my-project-name
kullanır.
Bir derlemenin kök ad alanı derleme adından farklıysa:
- Yerelleştirme varsayılan olarak çalışmaz.
- Yerelleştirme, kaynakların derleme içinde aranma şeklinden dolayı başarısız oluyor.
RootNamespace
, yürütme işlemi tarafından kullanılamayan bir derleme zamanı değeridir.
RootNamespace
dosyasından AssemblyName
farklıysa, aşağıdakini ekleyin AssemblyInfo.cs
(parametre değerleri gerçek değerlerle değiştirilir):
using System.Reflection;
using Microsoft.Extensions.Localization;
[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]
Yukarıdaki kod, resx dosyalarının başarılı bir şekilde çözümlenmesine olanak tanır.
Kültür geri dönüş davranışı
Bir kaynağı ararken, yerelleştirme "kültür geri dönüşü" ile etkileşim kurar. İstenen kültürden başlayarak, bulunamazsa, bu kültürün üst kültürüne geri döner. Bir yana, CultureInfo.Parent özelliği üst kültürü temsil eder. Bu genellikle (ancak her zaman değil), ulusal işaretleyiciyi dil ve kültür kodundan kaldırma anlamına gelir. Örneğin, Meksika'da İspanyolca konuşulan diyalekt "es-MX" şeklindedir. Üst "es" (herhangi bir ülkeye özgü olmayan İspanyolca) vardır.
Sitenizin "fr-CA" kültürünü kullanarak bir "Hoş Geldiniz" kaynağı isteği aldığını düşünün. Yerelleştirme sistemi sırayla aşağıdaki kaynakları arar ve ilk eşleşmeyi seçer:
- Welcome.fr-CA.resx
- Welcome.fr.resx
- Welcome.resx ("fr-CA" ise
NeutralResourcesLanguage
)
Örneğin, ".fr" kültür belirleyicisini kaldırırsanız ve kültür Fransızca olarak ayarlanırsa, varsayılan kaynak dosyası okunur ve dizeler yerelleştirilir. Resource manager, istenen kültürünüzü hiçbir şey karşılamadığında için varsayılan veya geri dönüş kaynağı belirtir. İstenen kültür için bir kaynak eksikken anahtarı döndürmek istiyorsanız, varsayılan kaynak dosyanız olmamalıdır.
Visual Studio ile kaynak dosyaları oluşturma
Visual Studio'da dosya adında bir kültür olmadan bir kaynak dosyası oluşturursanız (örneğin, Welcome.resx), Visual Studio her dize için bir özelliği olan bir C# sınıfı oluşturur. Genellikle ASP.NET Core'da istediğiniz bu değildir. Normalde varsayılan bir .resx kaynak dosyanız (kültür adı olmayan bir .resx dosyası) yoktur. .resx dosyasını bir kültür adıyla (örneğin Welcome.fr.resx) oluşturmanızı öneririz. Kültür adıyla bir .resx dosyası oluşturduğunuzda, Visual Studio sınıf dosyasını oluşturmaz.
Diğer kültürleri ekleme
Her dil ve kültür bileşimi (varsayılan dil dışında) benzersiz bir kaynak dosyası gerektirir. Dil kodlarının dosya adının bir parçası olduğu yeni kaynak dosyaları (örneğin, en-us, fr-ca ve en-gb) oluşturarak farklı kültürler ve yerel ayarlar için kaynak dosyaları oluşturursunuz. Bu kodlar, Welcome.es-MX.resx (İspanyolca/Meksika) içinde olduğu gibi dosya adı ile .resx dosya uzantısı arasına yerleştirilir.
Sonraki adımlar
Bir uygulamayı yerelleştirmek aşağıdaki görevleri de içerir:
- Uygulamanın içeriğini yerelleştirilebilir hale getirin.
- Her istek için dil/kültür seçmek için bir strateji uygulama
Ek kaynaklar
- ASP.NET Core'da genelleştirme ve yerelleştirme
- ASP.NET Core uygulamasının içeriğini yerelleştirilebilir hale getirme
- Yerelleştirilmiş ASP.NET Core uygulamasında dil ve kültür seçme stratejileri
- ASP.NET Çekirdek yerelleştirme sorunlarını giderme
- .NET uygulamalarını genelleştirme ve yerelleştirme
- Makalede kullanılan Localization.StarterWeb projesi .
- .resx Dosyalarındaki Kaynaklar
- Microsoft Çok Dilli Uygulama Araç Seti
- Yerelleştirme ve Genel Değerler
ASP.NET Core