.NET'te yerelleştirme

2025-06-17

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, IStringLocalizer<T> ve IStringLocalizerFactory uygulamalarını nasıl kullanacağınızı öğreneceksiniz. Bu makaledeki tüm örnek kaynak kodu, Microsoft.Extensions.Localization ve Microsoft.Extensions.Hosting NuGet paketlerine 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üketici uygulamanın çalıştırılmasından önce çevrilir; başka bir deyişle, hazır durumdaki ç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

Nerede:

<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 en azından dili 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 (Türkçe)
MessageService.sr-Cyrl.resx	Kiril alfabesi
MessageService.sr-Latn-BA.resx	(Latin, Bosna-Hersek)	Sanat Lisansı
MessageService.sr-Latn-ME.resx	(Latin, Karadağ)	BENİ
MessageService.sr-Latn-RS.resx	(Latin, Sırbistan)	RS (Türkçe)
MessageService.sr-Latn.resx	Latince
MessageService.sr.resx	^† Latince
MessageService.resx

^† Dil için varsayılan bölgesel dil.

Uygulamanız bir yerelleştirme kültürü CultureInfo.CurrentCulture kümesiyle "sr-Cyrl-RS" ç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 hizmetlerine bir ipucu sağlamak üzere RootNamespaceAttribute kullanın. Sağlandığında, kaynak arama sırasında kullanılır.

Örnek proje, birexample.dllveexample.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

AddLocalization(IServiceCollection, Action<LocalizationOptions>) aşırı yüklemesi, setupAction türünde bir Action<LocalizationOptions> parametresini 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.
Çağrı AddLocalization yaparak hizmet koleksiyonunda LocalizationOptions.ResourcesPath olarak "Resources" belirtir.

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, IStringLocalizer.Item[String]'yi bağımsız değişken olarak geçirerek "GreetingMessage"'i çağırır.

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.
Ana oluşturucu, IStringLocalizerFactory türünden bir IStringLocalizer oluşturmak için kullanılan bir ParameterizedMessageService parametresini alır ve _localizer alanına atar.
GetFormattedMessage yöntemi IStringLocalizer.Item[String, Object[]] öğesini, "DinnerPriceFormat" öğesini, bir dateTime nesnesini ve dinnerPrice öğesini argüman olarak kabul ederek çağırır.

Önemli

IStringLocalizerFactory gerekli değildir. Bunun yerine, IStringLocalizer<T>'yi gerektiren hizmetlerin tüketilmesi tercih edilir.

Her iki dizin oluşturucu da IStringLocalizer.Item[] dönüştürülebilen bir LocalizedString dö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:

RootNamespaceAttribute, "Localization.Example"'i kök ad alanı olarak ayarlar.
Console.OutputEncoding Encoding.Unicode'e atanmıştır.
tek bir bağımsız değişken geçtiğinde, args öğesine, CultureInfo.CurrentCulture ve CultureInfo.CurrentUICulture öğelerine, CultureInfo.GetCultureInfo(String) verilmiş arg[0] sonucu atanır.
Host varsayılan değerlerle oluşturulur.
Bu yerelleştirme hizmetleri, MessageService, ve ParameterizedMessageService DI için IServiceCollection'ye kaydedilir.
Gürültüyü gidermek için günlük kaydı, uyarı seviyesinden daha düşük günlük seviyelerini yoksayacak şekilde yapılandırılır.
MessageService örneği IServiceProvider örneğinden çözümlenir ve elde edilen mesaj günlüğe kaydedilir.
ParameterizedMessageService örneğinden IServiceProvider çözülür ve sonuçta elde edilen biçimlendirilmiş ileti 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 ile başlayarak kaynak dosyaları için ö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 ile başlayarak kaynak dosyaları için ö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>

Tavsiye

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ı kullanılırken bir bağımsız değişkeni atladığınızda, varsayılan sistem kültürü kullanılır—bu durumda:

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 $.

Ayrıca bakınız

.NET uygulamalarını genelleştirme ve yerelleştirme
.NET uygulamalarında kaynakları paketleme ve dağıtma
Microsoft.Extensions.Localization
.NET'te bağımlılık ekleme
.NET 'da Günlük Kaydı
ASP.NET Çekirdek yerelleştirmesi

Aracılığıyla paylaş

.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 bakınız

Geri Bildirim

Ek kaynaklar

ve kullanın `IStringLocalizer<T>IStringLocalizerFactory`