.NET'te yerelleştirme

Makale
02/02/2024

Yerelleştirme, bir uygulamanın kaynaklarını uygulamanın destekleyecekleri her kültür için yerelleştirilmiş sürümlere çevirme işlemidir. Yerelleştirme adımına yalnızca Yerelleştirilebilirlik gözden geçirme adımını tamamladıktan sonra devam ederek genelleştirilmiş uygulamanın yerelleştirme için hazır olduğunu doğrulamanız gerekir.

Yerelleştirme için hazır bir uygulama iki kavramsal bloka ayrılır: tüm kullanıcı arabirimi öğelerini içeren bir blok ve yürütülebilir kod içeren bir blok. Kullanıcı arabirimi bloğu yalnızca bağımsız kültür için dizeler, hata iletileri, iletişim kutuları, menüler, katıştırılmış nesne kaynakları gibi yerelleştirilebilir kullanıcı arabirimi öğelerini içerir. Kod bloğu yalnızca desteklenen tüm kültürler tarafından kullanılacak uygulama kodunu içerir. Ortak dil çalışma zamanı, bir uygulamanın yürütülebilir kodunu kaynaklarından ayıran bir uydu derleme kaynak modelini destekler. Bu modeli uygulama hakkında daha fazla bilgi için bkz . .NET'teki kaynaklar.

Uygulamanızın her yerelleştirilmiş sürümü için, hedef kültür için uygun dile çevrilmiş yerelleştirilmiş kullanıcı arabirimi bloğunu içeren yeni bir uydu derlemesi ekleyin. Tüm kültürler için kod bloğu aynı kalmalıdır. Kullanıcı arabirimi bloğunun yerelleştirilmiş bir sürümünün kod bloğuyla birleşimi uygulamanızın yerelleştirilmiş bir sürümünü oluşturur.

Bu makalede ve IStringLocalizerFactory uygulamalarını kullanmayı IStringLocalizer<T> öğreneceksiniz. Bu makaledeki örnek kaynak kodunun tümü ve Microsoft.Extensions.Hosting NuGet paketlerine Microsoft.Extensions.Localization dayanır. Barındırma hakkında daha fazla bilgi için bkz . .NET Genel Ana Bilgisayarı.

Kaynak dosyalar

Yerelleştirilebilir dizeleri yalıtma için birincil mekanizma kaynak dosyalarıdır. Kaynak dosyası, .resx dosya uzantısına sahip bir XML dosyasıdır. Kaynak dosyaları, tüketen uygulamanın yürütülmesinden önce çevrilir; başka bir deyişle bekleyen çevrilmiş içeriği temsil eder. Kaynak dosyası adı en yaygın olarak bir yerel ayar tanımlayıcısı içerir ve aşağıdaki formu alır:

<FullTypeName><.Locale>.resx

Where:

<FullTypeName>, belirli bir tür için yerelleştirilebilir kaynakları temsil eder.
isteğe bağlı <.Locale> , kaynak dosya içeriğinin yerel ayarını temsil eder.

Yerel ayarları belirtme

Yerel ayar dili en az bir şekilde tanımlamalıdır, ancak kültürü (bölgesel dil) ve hatta ülke veya bölgeyi de tanımlayabilir. Bu segmentler genellikle karakterle - sınırlandırılır. Bir kültürün ek özgüllüğüyle, en iyi eşleşmelerin önceliklendirildiği "kültür geri dönüşü" kuralları uygulanır. Yerel ayar iyi bilinen bir dil etiketiyle eşlenmelidir. Daha fazla bilgi için bkz. CultureInfo.Name.

Kültür geri dönüş senaryoları

Yerelleştirilmiş uygulamanızın çeşitli Sırp yerel ayarlarını desteklediğini ve uygulaması için aşağıdaki kaynak dosyalarına MessageServicesahip olduğunu düşünün:

Dosya	Bölgesel dil	Ülke Kodu
MessageService.sr-Cyrl-RS.resx	(Kiril, Sırbistan)	RS
MessageService.sr-Cyrl.resx	Kiril
MessageService.sr-Latn-BA.resx	(Latin, Bosna-Hersek)	BA
MessageService.sr-Latn-ME.resx	(Latin, Karadağ)	ME
MessageService.sr-Latn-RS.resx	(Latin, Sırbistan)	RS
MessageService.sr-Latn.resx	Latin
MessageService.sr.resx	latin †
MessageService.resx

† Dilin varsayılan bölgesel dilidir.

Uygulamanız bir yerelleştirme kültürü "sr-Cyrl-RS" kümesiyle CultureInfo.CurrentCulture çalışırken dosyaları aşağıdaki sırayla çözümlemeye çalışır:

MessageService.sr-Cyrl-RS.resx
MessageService.sr-Cyrl.resx
MessageService.sr.resx
MessageService.resx

Ancak, uygulamanız kümeyle yerelleştirme CultureInfo.CurrentCulture kültürüne "sr-Latn-BA" ayarlanmış olarak çalışıyorsa dosyaları aşağıdaki sırayla çözümlemeye çalışır:

MessageService.sr-Latn-BA.resx
MessageService.sr-Latn.resx
MessageService.sr.resx
MessageService.resx

"Kültür geri dönüş" kuralı, karşılık gelen eşleşmeler olmadığında yerel ayarları yoksayar; başka bir deyişle eşleşme bulamazsa dört numaralı kaynak dosya seçilir. Kültür olarak "fr-FR"ayarlandıysa, yerelleştirme sorunlu olabilecek MessageService.resx dosyasına düşebilir. Daha fazla bilgi için bkz . Kaynak geri dönüş işlemi.

Kaynak arama

Kaynak dosyaları, arama yordamının bir parçası olarak otomatik olarak çözümlenir. Proje dosyanızın adı projenizin kök ad alanından farklıysa, derleme adı farklı olabilir. Bu, kaynak aramanın aksi takdirde başarılı olmasını engelleyebilir. Bu uyuşmazlığı gidermek için yerelleştirme RootNamespaceAttribute hizmetlerine bir ipucu sağlamak için kullanın. Sağlandığında, kaynak arama sırasında kullanılır.

Örnek proje, bir example.dll ve example.exe oluşturan example.csproj adlı projedir; ancak Localization.Example ad alanı kullanılır. Bu uyuşmazlığı düzeltmek için bir assembly düzey özniteliği uygulayın:

[assembly: RootNamespace("Localization.Example")]

Yerelleştirme hizmetlerini kaydetme

Yerelleştirme hizmetlerini kaydetmek için, hizmetlerin yapılandırması sırasında uzantı yöntemlerinden birini AddLocalization çağırın. Bu, aşağıdaki türlerde bağımlılık eklemeyi (DI) etkinleştirir:

Yerelleştirme seçeneklerini yapılandırma

Aşırı AddLocalization(IServiceCollection, Action<LocalizationOptions>) yükleme türündeki Action<LocalizationOptions>bir setupAction parametreyi kabul eder. Bu, yerelleştirme seçeneklerini yapılandırmanıza olanak tanır.

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddLocalization(options =>
{
    options.ResourcesPath = "Resources";
});

// Omitted for brevity.

Kaynak dosyaları projenin herhangi bir yerinde bulunabilir, ancak başarılı olduğu kanıtlanmış yaygın uygulamalar vardır. Çoğu zaman, en az direnç yolu izlenir. Yukarıdaki C# kodu:

Varsayılan konak uygulama oluşturucusunu oluşturur.
Hizmet koleksiyonunda çağrısı AddLocalization yaparak olarak "Resources"belirtirLocalizationOptions.ResourcesPath.

Bu, yerelleştirme hizmetlerinin kaynak dosyaları için Kaynaklar dizinine bakmasına neden olur.

ve kullanın `IStringLocalizer<T>IStringLocalizerFactory`

Yerelleştirme hizmetlerini kaydettikten (ve isteğe bağlı olarak yapılandırdıktan) sonra AŞAĞıDAKI türleri DI ile kullanabilirsiniz:

Yerelleştirilmiş dizeleri döndürebilen bir ileti hizmeti oluşturmak için aşağıdakileri MessageServicegöz önünde bulundurun:

using System.Diagnostics.CodeAnalysis;
using Microsoft.Extensions.Localization;

namespace Localization.Example;

public sealed class MessageService(IStringLocalizer<MessageService> localizer)
{
    [return: NotNullIfNotNull(nameof(localizer))]
    public string? GetGreetingMessage()
    {
        LocalizedString localizedString = localizer["GreetingMessage"];

        return localizedString;
    }
}

Yukarıdaki C# kodunda:

Bir IStringLocalizer<MessageService> localizer alan bildirilir.
Birincil oluşturucu bir IStringLocalizer<MessageService> parametre tanımlar ve bunu bağımsız localizer değişken olarak yakalar.
GetGreetingMessage yöntemi geçişi "GreetingMessage" bağımsız değişken olarak çağırırIStringLocalizer.Item[String].

IStringLocalizer Parametresiz dize kaynaklarını da destekler, aşağıdakileri ParameterizedMessageServicegöz önünde bulundurun:

using System.Diagnostics.CodeAnalysis;
using Microsoft.Extensions.Localization;

namespace Localization.Example;

public class ParameterizedMessageService(IStringLocalizerFactory factory)
{
    private readonly IStringLocalizer _localizer =
        factory.Create(typeof(ParameterizedMessageService));

    [return: NotNullIfNotNull(nameof(_localizer))]
    public string? GetFormattedMessage(DateTime dateTime, double dinnerPrice)
    {
        LocalizedString localizedString = _localizer["DinnerPriceFormat", dateTime, dinnerPrice];

        return localizedString;
    }
}

Yukarıdaki C# kodunda:

Bir IStringLocalizer _localizer alan bildirilir.
Birincil oluşturucu, türünden ParameterizedMessageService bir oluşturmak için kullanılan bir IStringLocalizerFactoryIStringLocalizer parametre alır ve bu parametreyi _localizer alana atar.
GetFormattedMessage yöntemi, bir nesnesi ve dinnerPrice bağımsız değişken olarak öğesini dateTime"DinnerPriceFormat"çağırırIStringLocalizer.Item[String, Object[]].

Önemli

IStringLocalizerFactory gerekli değildir. Bunun yerine, hizmetlerinin kullanılmasını gerektirmek IStringLocalizer<T>için tercih edilir.

Her iki dizin oluşturucu da IStringLocalizer.Item[] örtük dönüştürmeleri string? olan bir LocalizedStringdöndürür.

Hepsini bir araya getirin

Yerelleştirme ve kaynak dosyalarıyla birlikte hem ileti hizmetlerini kullanarak bir uygulamayı örneklendirmek için aşağıdaki Program.cs dosyasını göz önünde bulundurun:

using System.Globalization;
using Localization.Example;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Localization;
using Microsoft.Extensions.Logging;
using static System.Console;
using static System.Text.Encoding;

[assembly: RootNamespace("Localization.Example")]

OutputEncoding = Unicode;

if (args is [var cultureName])
{
    CultureInfo.CurrentCulture =
        CultureInfo.CurrentUICulture =
            CultureInfo.GetCultureInfo(cultureName);
}

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddLocalization();
builder.Services.AddTransient<MessageService>();
builder.Services.AddTransient<ParameterizedMessageService>();
builder.Logging.SetMinimumLevel(LogLevel.Warning);

using IHost host = builder.Build();

IServiceProvider services = host.Services;

ILogger logger =
    services.GetRequiredService<ILoggerFactory>()
        .CreateLogger("Localization.Example");

MessageService messageService =
    services.GetRequiredService<MessageService>();
logger.LogWarning(
    "{Msg}",
    messageService.GetGreetingMessage());

ParameterizedMessageService parameterizedMessageService =
    services.GetRequiredService<ParameterizedMessageService>();
logger.LogWarning(
    "{Msg}",
    parameterizedMessageService.GetFormattedMessage(
        DateTime.Today.AddDays(-3), 37.63));

await host.RunAsync();

Yukarıdaki C# kodunda:

kök RootNamespaceAttribute ad alanı olarak ayarlar "Localization.Example" .
Console.OutputEncoding öğesine atanırEncoding.Unicode.
öğesine tek bir bağımsız değişken geçirildiğinde argsCultureInfo.CurrentCulture ve CultureInfo.CurrentUICulture öğesine verilen arg[0]sonucu CultureInfo.GetCultureInfo(String) atanır.
Host varsayılan değerlerle oluşturulur.
yerelleştirme hizmetleri, MessageServiceve ParameterizedMessageService için DI'ye IServiceCollection kaydedilir.
Gürültüyü gidermek için günlük kaydı, uyarıdan daha düşük günlük düzeylerini yoksayacak şekilde yapılandırılır.
MessageService örneği çözümlenir IServiceProvider ve sonuçta elde edilen ileti günlüğe kaydedilir.
ParameterizedMessageService örnekten IServiceProvider çözümlenir ve sonuçta biçimlendirilmiş iletisi günlüğe kaydedilir.

Sınıfların *MessageService her biri, her biri tek bir girişe sahip bir .resx dosyası kümesi tanımlar. MessageService.resx ile başlayarak kaynak dosyaları için MessageService örnek içerik aşağıda verilmiştir:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <data name="GreetingMessage" xml:space="preserve">
    <value>Hi friends, the ".NET" developer community is excited to see you here!</value>
  </data>
</root>

MessageService.sr-Cyrl-RS.resx:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <data name="GreetingMessage" xml:space="preserve">
    <value>Здраво пријатељи, ".NЕТ" девелопер заједница је узбуђена што вас види овде!</value>
  </data>
</root>

MessageService.sr-Latn.resx:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <data name="GreetingMessage" xml:space="preserve">
    <value>Zdravo prijatelji, ".NET" developer zajednica je uzbuđena što vas vidi ovde!</value>
  </data>
</root>

ParameterizedMessageService.resx ile başlayarak kaynak dosyaları için ParameterizedMessageService örnek içerik aşağıda verilmiştir:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <data name="DinnerPriceFormat" xml:space="preserve">
    <value>On {0:D} my dinner cost {1:C}.</value>
  </data>
</root>

ParameterizedMessageService.sr-Cyrl-RS.resx:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <data name="DinnerPriceFormat" xml:space="preserve">
    <value>У {0:D} моја вечера је коштала {1:C}.</value>
  </data>
</root>

ParameterizedMessageService.sr-Latn.resx:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <data name="DinnerPriceFormat" xml:space="preserve">
    <value>U {0:D} moja večera je koštala {1:C}.</value>
  </data>
</root>

İpucu

Kaynak dosyası XML açıklamalarının, şemasının ve <resheader> öğelerinin tümü kısa süre için kasıtlı olarak atlanır.

Örnek çalıştırmalar

Aşağıdaki örnek çalıştırmalar, hedeflenen yerel ayarlara göre çeşitli yerelleştirilmiş çıkışları gösterir.

Göz önünde bulundurun "sr-Latn":

dotnet run --project .\example\example.csproj sr-Latn

warn: Localization.Example[0]
      Zdravo prijatelji, ".NET" developer zajednica je uzbuđena što vas vidi ovde!
warn: Localization.Example[0]
      U utorak, 03. avgust 2021. moja večera je koštala 37,63 ¤.

Projeyi çalıştırmak için .NET CLI'sına bir bağımsız değişken atlanırken, varsayılan sistem kültürü kullanılır; bu durumda"en-US":

dotnet run --project .\example\example.csproj

warn: Localization.Example[0]
      Hi friends, the ".NET" developer community is excited to see you here!
warn: Localization.Example[0]
      On Tuesday, August 3, 2021 my dinner cost $37.63.

geçirilirken "sr-Cryl-RS", ilgili doğru kaynak dosyaları bulunur ve yerelleştirme uygulanır:

dotnet run --project .\example\example.csproj sr-Cryl-RS

warn: Localization.Example[0]
      Здраво пријатељи, ".NЕТ" девелопер заједница је узбуђена што вас види овде!
warn: Localization.Example[0]
      У уторак, 03. август 2021. моја вечера је коштала 38 RSD.

Örnek uygulama için "fr-CA"kaynak dosyaları sağlamaz, ancak bu kültürle birlikte çağrıldığında, yerelleştirilmemiş kaynak dosyaları kullanılır.

Uyarı

Kültür bulunduğundan ancak doğru kaynak dosyaları bulunmadığından, biçimlendirme uygulandığında kısmi yerelleştirmeyle sonuçlanırsınız:

dotnet run --project .\example\example.csproj fr-CA

warn: Localization.Example[0]
     Hi friends, the ".NET" developer community is excited to see you here!
warn: Localization.Example[0]
     On mardi 3 août 2021 my dinner cost 37,63 $.

.NET'te yerelleştirme

Kaynak dosyalar

Yerel ayarları belirtme

Kültür geri dönüş senaryoları

Kaynak arama

Yerelleştirme hizmetlerini kaydetme

Yerelleştirme seçeneklerini yapılandırma

ve kullanın `IStringLocalizer<T>IStringLocalizerFactory`

Hepsini bir araya getirin

Örnek çalıştırmalar

Ayrıca bkz.

Geri Bildirim

Ek kaynaklar

.NET'te yerelleştirme

Kaynak dosyalar

Yerel ayarları belirtme

Kültür geri dönüş senaryoları

Kaynak arama

Yerelleştirme hizmetlerini kaydetme

Yerelleştirme seçeneklerini yapılandırma

ve kullanın IStringLocalizer<T>IStringLocalizerFactory

Hepsini bir araya getirin

Örnek çalıştırmalar

Ayrıca bkz.

Geri Bildirim

Ek kaynaklar

ve kullanın `IStringLocalizer<T>IStringLocalizerFactory`