Honosítás a .NET-ben

A honosítás az alkalmazás erőforrásainak honosított verziókká történő lefordításának folyamata minden olyan kultúrához, amelyet az alkalmazás támogatni fog. A honosítási lépéshez csak a honosítási felülvizsgálati lépés elvégzése után kell továbblépnie, hogy ellenőrizze, hogy a globalizált alkalmazás készen áll-e a honosításra.

A honosításra kész alkalmazás két fogalmi blokkra van osztva: egy blokkra, amely tartalmazza az összes felhasználói felületi elemet és egy végrehajtható kódot tartalmazó blokkot. A felhasználói felület blokkja csak honosítható felhasználói felületi elemeket tartalmaz, például sztringeket, hibaüzeneteket, párbeszédpaneleket, menüket, beágyazott objektumerőforrásokat stb. a semleges kultúra számára. A kódblokk csak az összes támogatott kultúra által használandó alkalmazáskódot tartalmazza. A közös nyelvi futtatókörnyezet támogatja a műholdas szerelvény erőforrásmodelljét, amely elválasztja az alkalmazás végrehajtható kódját az erőforrásaitól. A modell implementálásával kapcsolatos további információkért lásd: Erőforrások a .NET-ben.

Az alkalmazás minden honosított verziójához adjon hozzá egy új műholdas szerelvényt, amely a célkultúra megfelelő nyelvére lefordított honosított felhasználói felületi blokkot tartalmazza. Az összes kultúra kódblokkjának változatlannak kell maradnia. A felhasználói felület blokkjának honosított verziójának és a kódblokknak a kombinációja létrehozza az alkalmazás honosított verzióját.

Ebben a cikkben megtudhatja, hogyan használhatja az IStringLocalizer<T> és IStringLocalizerFactory implementációkat. A cikkben szereplő összes példaforráskód a Microsoft.Extensions.Localization NuGet-csomagokra Microsoft.Extensions.Hosting támaszkodik. További információ az üzemeltetésről: .NET Generic Host.

Erőforrásfájlok

A honosítható sztringek elkülönítésének elsődleges mechanizmusa az erőforrásfájlok. Az erőforrásfájl egy .resx kiterjesztésű XML-fájl. Az erőforrásfájlokat a rendszer a fogyasztó alkalmazás végrehajtása előtt fordítja le, vagyis a lefordított tartalmat inaktív állapotban jeleníti meg. Az erőforrásfájl neve leggyakrabban helykóddal azonosítja magát, és a következő formát ölti:

<FullTypeName><.Locale>.resx

Helyszín:

• Az <FullTypeName> adott típushoz tartozó honosítható erőforrásokat jelöli.
• Az opcionális <.Locale> az erőforrásfájl tartalmának területi beállítását jelöli.

Területi beállítások megadása

A területi beállításnak minimálisan meg kell határoznia a nyelvet, de meghatározhatja a kultúrát (regionális nyelvet), és akár az országot vagy régiót is. Ezeket a szegmenseket általában a - karakter tagolja. A kultúra hozzáadott sajátosságával a "kulturális tartalék" szabályok érvényesülnek, ahol a legjobb egyezések kerülnek rangsorolásra. A helyi beállításnak egy jól ismert nyelvi címkének kell megfelelnie. További információért lásd CultureInfo.Name.

Kulturális tartalék forgatókönyvek

Tegyük fel, hogy a honosított alkalmazás támogatja a különböző szerb területi beállításokat, és a következő erőforrásfájlokkal rendelkezik:MessageService

Fájl	Regionális nyelv	Országkód
MessageService.sr-Cyrl-RS.resx	(Cirill betűs, Szerbia)	RS
MessageService.sr-Cyrl.resx	Cirill ábécé
MessageService.sr-Latn-BA.resx	(Latin, Bosznia és Hercegovina)	Bölcsészdiploma
MessageService.sr-Latn-ME.resx	(latin betűs, montenegrói)	ÉN
MessageService.sr-Latn-RS.resx	(Latin, Szerbia)	RS
MessageService.sr-Latn.resx	Latin
MessageService.sr.resx	† Latin
MessageService.resx

^† A nyelv alapértelmezett regionális nyelve.

Ha az alkalmazás a CultureInfo.CurrentCulture honosítási kultúra "sr-Cyrl-RS" halmazával fut, a következő sorrendben próbálja feloldani a fájlokat:

1. MessageService.sr-Cyrl-RS.resx
2. MessageService.sr-Cyrl.resx
3. MessageService.sr.resx
4. MessageService.resx

Ha azonban az alkalmazás a CultureInfo.CurrentCulture honosítási kultúra "sr-Latn-BA" halmazával futott, a következő sorrendben próbálja feloldani a fájlokat:

1. MessageService.sr-Latn-BA.resx
2. MessageService.sr-Latn.resx
3. MessageService.sr.resx
4. MessageService.resx

A "kulturális tartalék" szabály figyelmen kívül hagyja a területi beállításokat, ha nincsenek megfelelő egyezések, ami azt jelenti, hogy a negyedik erőforrásfájl van kiválasztva, ha nem talál egyezést. Ha a kultúra beállítva van "fr-FR", a honosítást a MessageService.resx fájl kezeli, ami problémás lehet. További információ: Az erőforrás-tartalék folyamat.

Erőforrás-keresés

Az erőforrásfájlok automatikusan feloldódnak egy keresési rutin részeként. Ha a projektfájl neve eltér a projekt gyökérnévterétől, az összeállítás neve eltérhet. Ez megakadályozhatja, hogy az erőforrás-keresés egyébként sikeres legyen. Ennek a eltérésnek a megoldásához használja a RootNamespaceAttribute honosítási szolgáltatásokra vonatkozó tippet. Ha meg van adva, azt az erőforrás-keresés során használja a rendszer.

A példaprojekt neve example.csproj, amely létrehoz egy example.dll és example.exe– a névteret azonban a Localization.Example rendszer használja. Alkalmazzon egy assembly szintattribútumot az eltérés kijavításához:

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

Honosítási szolgáltatások regisztrálása

A honosítási szolgáltatások regisztrálásához hívja meg az AddLocalization egyik bővítménymetelyt a szolgáltatások konfigurálása során. Ez lehetővé teszi a függőséginjektálást (DI) a következő típusok közül:

• Microsoft.Extensions.Localization.IStringLocalizer<T>
• Microsoft.Extensions.Localization.IStringLocalizerFactory

Honosítási beállítások konfigurálása

A AddLocalization(IServiceCollection, Action<LocalizationOptions>) túlterhelés elfogad egy típusú setupActionparamétertAction<LocalizationOptions>. Ez lehetővé teszi a honosítási beállítások konfigurálását.

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

// Omitted for brevity.

Az erőforrásfájlok bárhol élhetnek egy projektben, de léteznek olyan gyakori eljárások, amelyek sikeresnek bizonyultak. Gyakrabban, mint nem, a legkisebb ellenállás útját követik. Az előző C# kód:

• Létrehozza az alapértelmezett gazdagépalkalmazás-szerkesztőt.
• Hívja meg a szolgáltatásgyűjteményt AddLocalization, megadva LocalizationOptions.ResourcesPath mint "Resources".

Ez azt eredményezné, hogy a honosítási szolgáltatások az erőforrásfájlok Erőforrás könyvtárában keresnek.

Használat IStringLocalizer<T> és IStringLocalizerFactory

Miután regisztrálta (és opcionálisan konfigurálta) a honosítási szolgáltatásokat, a következő típusokat használhatja a diával:

• IStringLocalizer<T>
• IStringLocalizerFactory

Honosított sztringek visszaadására alkalmas üzenetszolgáltatás létrehozásához vegye figyelembe a következőket MessageService:

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;
    }
}

Az előző C# kódban:

• A program deklarál egy IStringLocalizer<MessageService> localizer mezőt.
• Az elsődleges konstruktor meghatároz egy paramétert IStringLocalizer<MessageService> , és argumentumként localizer rögzíti azt.
• A GetGreetingMessage metódus meghívja a IStringLocalizer.Item[String]-t, átadva a "GreetingMessage"-t argumentumként.

A IStringLocalizer paraméteres sztringerőforrásokat is támogatja, vegye figyelembe a következőket ParameterizedMessageService:

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;
    }
}

Az előző C# kódban:

• A program deklarál egy IStringLocalizer _localizer mezőt.
• Az elsődleges konstruktor egy IStringLocalizerFactory paramétert vesz fel, amelyet a IStringLocalizer típusból hoz létre, és hozza létre a ParameterizedMessageService értéket, majd hozzárendeli a _localizer mezőhöz.
• A GetFormattedMessage metódus meghívja a IStringLocalizer.Item[String, Object[]]-t, argumentumként átadva a "DinnerPriceFormat"-t, egy dateTime objektumot, és a dinnerPrice-et.

Fontos

A IStringLocalizerFactory nem kötelező. Ehelyett az a preferált, ha a szolgáltatások igénybevételéhez szükséges a IStringLocalizer<T>.

Mindkét IStringLocalizer.Item[] indexelő visszaad egy LocalizedString, amely implicit konverzióval rendelkezikstring?.

Rakd össze az egészet

Ha az alkalmazásokat mind az üzenetszolgáltatások, mind a honosítási és erőforrásfájlok használatával szeretné szemléltetni, vegye figyelembe a következő Program.cs fájlt:

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();

Az előző C# kódban:

• A RootNamespaceAttribute"Localization.Example"-t gyökérnévtérként állítja be.
• Console.OutputEncoding hozzá van rendelve a Encoding.Unicode-hez.
• Amikor egyetlen argumentumot ad át a args, az CultureInfo.CurrentCulture és CultureInfo.CurrentUICulture az CultureInfo.GetCultureInfo(String) eredményét kapják meg arg[0] alapján.
• Az Hostalapértelmezett értékekkel jön létre.
• A honosítási szolgáltatások, MessageServiceés ParameterizedMessageService regisztrálva vannak a IServiceCollection DI-ben.
• A zaj eltávolításához a naplózás úgy van konfigurálva, hogy figyelmen kívül hagyja a figyelmeztetésnél alacsonyabb naplószinteket.
• A MessageService feloldódik a IServiceProvider példányból, és az eredményként kapott üzenet naplózásra kerül.
• A ParameterizedMessageService a IServiceProvider példányból kerül feloldásra, és a kapott formázott üzenet naplózásra kerül.

*MessageService Mindegyik osztály egy .resx fájlkészletet határoz meg, mindegyiket egyetlen bejegyzéssel. Íme az erőforrásfájlok példatartalma a MessageServiceMessageService.resx fájltól kezdve:

<?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>

Íme az erőforrásfájlok példatartalma a ParameterizedMessageServiceParameterizedMessageService.resx fájltól kezdve:

<?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>

Jótanács

A rendszer szándékosan kihagyja az erőforrásfájl XML-megjegyzéseit, sémáit és <resheader> elemeit a rövidség kedvéért.

Példafutások

Az alábbi példafuttatások a különböző honosított kimeneteket jelenítik meg, célzott területi beállításokkal.

Fontolja meg "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 ¤.

Amikor kihagy egy argumentumot a .NET CLI-nek a projekt futtatásához , az alapértelmezett rendszerkultúra lesz használatban – ebben az esetben "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.

Átadáskor "sr-Cryl-RS", a rendszer megtalálja a megfelelő erőforrásfájlokat és alkalmazza a honosítást.

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

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

A mintaalkalmazás nem biztosít erőforrásfájlokat a "fr-CA" számára, de amikor ezt a kultúrát használja, a rendszer a nem honosított erőforrásfájlokat használja.

Figyelmeztetés

Mivel a kultúra megtalálható, de a megfelelő erőforrásfájlok nem elérhetők, a formázás alkalmazásakor részleges lesz a honosítás.

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

Lásd még

• .NET-alkalmazások globalizálása és honosítása
• Erőforrások csomagolása és üzembe helyezése .NET-alkalmazásokban
• Microsoft.Extensions.Localization
• Függőséginjektálás a .NET-ben
• Naplózás a .NET-ben
• ASP.NET Core-honosítás