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 a megvalósításokat és IStringLocalizerFactory az IStringLocalizer<T> 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 területi azonosítót tartalmaz, és a következő űrlapot veszi fel:

<FullTypeName><.Locale>.resx

Ahol:

• 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 területi beállításnak egy jól ismert nyelvi címkére kell képeznie. További információ: 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

† 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 kulturális környezet be van állítva "fr-FR", a honosítás a MessageService.resx fájlba kerül, 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, a szerelvény 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évtér azonban Localization.Example használatban van. 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ú Action<LocalizationOptions>paramétertsetupAction. 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 AddLocalization meg a szolgáltatásgyűjteményt, és adja meg a következőt LocalizationOptions.ResourcesPath"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 argumentumként hívja meg az IStringLocalizer.Item[String] átadást "GreetingMessage" .

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 paramétert IStringLocalizerFactory használ, amely a ParameterizedMessageService típusból hoz létre egy IStringLocalizer paramétert, és hozzárendeli a _localizer mezőhöz.
• A GetFormattedMessage metódus meghív, IStringLocalizer.Item[String, Object[]]átad "DinnerPriceFormat", egy dateTime objektumot, és dinnerPrice argumentumként.

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

Az alkalmazás összeállítása

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 az alábbi 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 készletek "Localization.Example" gyökérnévtérként szolgálnak.
• A Console.OutputEncoding program a következőhöz Encoding.Unicodevan rendelve: .
• Amikor egyetlen argumentumot ad át argsa rendszer, az CultureInfo.CurrentCultureCultureInfo.CurrentUICulture adott argumentum eredménye CultureInfo.GetCultureInfo(String) lesz hozzárendelve a megadott értékhez arg[0].
• Az Host alapé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 rendszer feloldja a IServiceProvider példányt, és az eredményként kapott üzenetet naplózza a rendszer.
• A ParameterizedMessageService rendszer feloldja a IServiceProvider példányt, és az eredményként kapott formázott üzenetet naplózza a rendszer.

*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 MessageService MessageService.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 ParameterizedMessageService ParameterizedMessageService.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>

Példafuttatá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.

Az átadáskor "sr-Cryl-RS"a rendszer a megfelelő erőforrásfájlokat találja, é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 nem honosított erőforrásfájlokhoz "fr-CA", de ha ezt a kultúrát meghívja, a rendszer a nem honosított erőforrásfájlokat használja.

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