Konfigurowanie lokalizacji obiektów przenośnych w programie ASP.NET Core

  • Artykuł

Przez Hisham Bin Ateya i Sébastien Ros.

W tym artykule przedstawiono procedurę używania plików obiektów przenośnych (PO) w aplikacji ASP.NET Core z platformą Sad Core .

Uwaga: Sad Core nie jest produktem firmy Microsoft. Firma Microsoft nie obsługuje tej funkcji.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Co to jest plik zamówienia zakupu?

Pliki zamówienia zakupu są dystrybuowane jako pliki tekstowe zawierające przetłumaczone ciągi dla danego języka. Niektóre zalety używania plików zamówienia zakupu zamiast plików resx obejmują:

  • Pliki zamówienia zakupu obsługują mnogią; Pliki resx nie obsługują liczby mnogiej.
  • Pliki zamówienia zakupu nie są kompilowane, takie jak pliki resx . W związku z tym wyspecjalizowane narzędzia i kroki kompilacji nie są wymagane.
  • Pliki zamówienia zakupu działają dobrze z narzędziami do wspólnego edytowania online.

Przykład

Poniższy przykładowy plik zamówienia zakupu zawiera tłumaczenie dwóch ciągów w języku francuskim, w tym jeden z jego postacią mnogią:

fr.po

#: Pages/Index.cshtml:13
msgid "Hello world!"
msgstr "Bonjour le monde!"

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."

W tym przykładzie użyto następującej składni:

  • #:: komentarz wskazujący kontekst ciągu, który ma zostać przetłumaczony. Ten sam ciąg może być tłumaczony inaczej w zależności od tego, gdzie jest używany.
  • msgid: nieprzetłumaczony ciąg.
  • msgstr: przetłumaczony ciąg.

W przypadku obsługi liczby mnogiej można zdefiniować więcej wpisów.

  • msgid_plural: nieprzetłumaczony ciąg w liczbie mnogiej.
  • msgstr[0]: przetłumaczony ciąg dla przypadku 0.
  • msgstr[N]: Przetłumaczony ciąg dla przypadku N.

Specyfikację pliku zamówienia zakupu można znaleźć tutaj.

Konfigurowanie obsługi plików zamówienia zakupu w programie ASP.NET Core

Ten przykład jest oparty na aplikacji internetowej ASP.NET Core wygenerowanej na podstawie szablonu projektu programu Visual Studio 2022.

Odwoływanie się do pakietu

Dodaj odwołanie do OrchardCore.Localization.Core pakietu NuGet.

Plik .csproj zawiera teraz wiersz podobny do następującego (numer wersji może się różnić):

<PackageReference Include="OrchardCore.Localization.Core" Version="1.5.0" />

Rejestrowanie usługi

Dodaj wymagane usługi do :Program.cs

builder.Services.AddPortableObjectLocalization();

builder.Services
    .Configure<RequestLocalizationOptions>(options => options
        .AddSupportedCultures("fr", "cs")
        .AddSupportedUICultures("fr", "cs"));

builder.Services
    .AddRazorPages()
    .AddViewLocalization();

Dodaj następujący kod do Razor wybranej strony. Index.cshtml jest używany w tym przykładzie.

@page
@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer
@{
    ViewData["Title"] = "Home";
}

<div class="text-center">
    <h1 class="display-4">Welcome</h1>
    <p>Learn about <a href="https://docs.microsoft.com/aspnet/core">building Web apps with ASP.NET Core</a>.</p>
</div>

<p>@Localizer["Hello world!"]</p>

Wystąpienie IViewLocalizer jest wstrzykiwane i używane do tłumaczenia tekstu "Hello world!".

Tworzenie pliku zamówienia zakupu

Utwórz plik o nazwie <culture code.po> w folderze głównym aplikacji. W tym przykładzie nazwa pliku to fr.po , ponieważ jest używany język francuski:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Ten plik przechowuje zarówno ciąg do tłumaczenia, jak i przetłumaczony po francusku ciąg. Tłumaczenia wracają do ich kultury nadrzędnej, jeśli to konieczne. W tym przykładzie plik fr.po jest używany, jeśli żądana kultura to fr-FR lub fr-CA.

Testowanie aplikacji

Uruchom aplikację, zostanie wyświetlony tekst Hello world!

Przejdź pod adres URL /Index?culture=fr-FR. Zostanie wyświetlony tekst Bonjour le monde!

Pluralizacja

Pliki zamówienia zakupu obsługują formularze pluralizacji, co jest przydatne, gdy ten sam ciąg musi być tłumaczony inaczej na podstawie kardynalności. To zadanie jest skomplikowane przez fakt, że każdy język definiuje reguły niestandardowe, aby wybrać ciąg do użycia na podstawie kardynalności.

Pakiet Lokalizacji Sad udostępnia interfejs API do automatycznego wywoływania tych różnych formularzy w liczbie mnogiej.

Tworzenie plików zamówienia zakupu w liczbie mnogiej

Dodaj następującą zawartość do wcześniej wymienionego pliku fr.po :

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."

Zobacz Co to jest plik zamówienia zakupu? aby uzyskać wyjaśnienie, co reprezentuje każdy wpis w tym przykładzie.

Dodawanie języka przy użyciu różnych formularzy mnogiej

W poprzednim przykładzie użyto ciągów angielskich i francuskich. Angielski i francuski mają tylko dwie formy liczby mnogiej i mają te same reguły formularza, co oznacza, że kardynalność jednego jest mapowana na pierwszą formę mnogią. Każda inna kardynalność jest mapowana na drugą postać mnogią.

Nie wszystkie języki mają te same reguły. Jest to zilustrowane językiem czeskim, który ma trzy formy mnogiej.

cs.po Utwórz plik w następujący sposób i zwróć uwagę, jak liczba mnogiej wymaga trzech różnych tłumaczeń:

msgid "Hello world!"
msgstr "Ahoj světe!!"

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Existuje jedna položka."
msgstr[1] "Existují {0} položky."
msgstr[2] "Existuje {0} položek."

Aby zaakceptować czeskie lokalizacje, dodaj "cs" do listy obsługiwanych kultur w metodzie Configure :

builder.Services
    .Configure<RequestLocalizationOptions>(options => options
        .AddSupportedCultures("fr", "cs")
        .AddSupportedUICultures("fr", "cs"));

Edytuj plik w celu renderowania Pages/Index.cshtml zlokalizowanych ciągów w liczbie mnogiej dla kilku kardynalizacji:

<p>@Localizer.Plural(1, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(2, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(5, "There is one item.", "There are {0} items.")</p>

Uwaga: W rzeczywistym scenariuszu zmienna będzie używana do reprezentowania liczby. W tym miejscu powtarzamy ten sam kod z trzema różnymi wartościami, aby uwidocznić konkretny przypadek.

Po przełączeniu kultur zobaczysz następujące elementy:

W przypadku wersji /Index:

There is one item.
There are 2 items.
There are 5 items.

W przypadku wersji /Index?culture=fr:

Il y a un élément.
Il y a 2 éléments.
Il y a 5 éléments.

W przypadku wersji /Index?culture=cs:

Existuje jedna položka.
Existují 2 položky.
Existuje 5 položek.

Dla kultury czeskiej trzy tłumaczenia są różne. Kultury francuskie i angielskie mają tę samą konstrukcję dla dwóch ostatnich przetłumaczonych ciągów.

Zaawansowane zadania

Kontekstowe ciągi

Aplikacje często zawierają ciągi, które mają być tłumaczone w kilku miejscach. Ten sam ciąg może mieć inne tłumaczenie w niektórych lokalizacjach w aplikacji (Razor widoki lub pliki klas). Plik zamówienia zakupu obsługuje pojęcie kontekstu pliku, który może służyć do kategoryzowania reprezentowanego ciągu. Przy użyciu kontekstu pliku ciąg może być tłumaczony inaczej, w zależności od kontekstu pliku (lub braku kontekstu pliku).

Usługi lokalizacji zamówienia zakupu używają nazwy pełnej klasy lub widoku używanego podczas tłumaczenia ciągu. Jest to realizowane przez ustawienie wartości wpisu msgctxt .

Rozważ drobny dodatek do poprzedniego przykładu fr.po . Stronę znajdującą Razor się w Pages/Index.cshtml lokalizacji można zdefiniować jako kontekst pliku, ustawiając wartość wpisu zarezerwowanego msgctxt :

msgctxt "Views.Home.About"
msgid "Hello world!"
msgstr "Bonjour le monde!"

Gdy zestaw jest taki msgctxt , tłumaczenie tekstu odbywa się podczas przechodzenia do /Index?culture=fr-FRelementu . Tłumaczenie nie występuje podczas przechodzenia do elementu /Privacy?culture=fr-FR.

Jeśli żaden konkretny wpis nie jest zgodny z danym kontekstem pliku, mechanizm rezerwowy Sad Core szuka odpowiedniego pliku zamówienia zakupu bez kontekstu. Przy założeniu, że nie zdefiniowano określonego kontekstu pliku dla Pages/Privacy.cshtmlprogramu , nawigowanie po /Privacy?culture=fr-FR załadowaniu pliku zamówienia zakupu, takiego jak:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Zmienianie lokalizacji plików zamówienia zakupu

Domyślną lokalizację plików zamówienia zakupu można zmienić w pliku Programs.cs:

services.AddPortableObjectLocalization(options => options.ResourcesPath = "Localization");

W tym przykładzie pliki zamówienia zakupu są ładowane z folderu Lokalizacja .

Implementowanie niestandardowej logiki do znajdowania plików lokalizacji

Gdy potrzebna jest bardziej złożona logika w celu zlokalizowania plików zamówienia zakupu, OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider interfejs można zaimplementować i zarejestrować jako usługę. Jest to przydatne, gdy pliki zamówienia zakupu mogą być przechowywane w różnych lokalizacjach lub gdy pliki muszą być znalezione w hierarchii folderów.

Używanie innego domyślnego języka w liczbie mnogiej

Pakiet zawiera metodę rozszerzenia specyficzną Plural dla dwóch form w liczbie mnogiej. W przypadku języków wymagających większej liczby formularzy w liczbie mnogiej utwórz metodę rozszerzenia. W przypadku metody rozszerzenia nie trzeba podawać żadnego pliku lokalizacji dla języka domyślnego — oryginalne ciągi są już dostępne bezpośrednio w kodzie.

Można użyć bardziej ogólnego Plural(int count, string[] pluralForms, params object[] arguments) przeciążenia, które akceptuje tablicę ciągów tłumaczeń.

Przez Sébastien Ros, Scott Addie i Hisham Bin Ateya

W tym artykule przedstawiono procedurę używania plików obiektów przenośnych (PO) w aplikacji ASP.NET Core z platformą Sad Core .

Uwaga: Sad Core nie jest produktem firmy Microsoft. W związku z tym firma Microsoft nie zapewnia pomocy technicznej dla tej funkcji.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Co to jest plik zamówienia zakupu?

Pliki zamówienia zakupu są dystrybuowane jako pliki tekstowe zawierające przetłumaczone ciągi dla danego języka. Niektóre zalety używania plików zamówienia zakupu zamiast plików resx obejmują:

  • Pliki zamówienia zakupu obsługują mnogią; Pliki resx nie obsługują liczby mnogiej.
  • Pliki zamówienia zakupu nie są kompilowane, takie jak pliki resx . W związku z tym wyspecjalizowane narzędzia i kroki kompilacji nie są wymagane.
  • Pliki zamówienia zakupu działają dobrze z narzędziami do wspólnego edytowania online.

Przykład

Oto przykładowy plik zamówienia zakupu zawierający tłumaczenie dwóch ciągów w języku francuskim, w tym jeden z jego postacią mnogią:

fr.po

#: Pages/Index.cshtml:13
msgid "Hello world!"
msgstr "Bonjour le monde!"

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."

W tym przykładzie użyto następującej składni:

  • #:: komentarz wskazujący kontekst ciągu, który ma zostać przetłumaczony. Ten sam ciąg może być tłumaczony inaczej w zależności od tego, gdzie jest używany.
  • msgid: nieprzetłumaczony ciąg.
  • msgstr: przetłumaczony ciąg.

W przypadku obsługi liczby mnogiej można zdefiniować więcej wpisów.

  • msgid_plural: nieprzetłumaczony ciąg w liczbie mnogiej.
  • msgstr[0]: przetłumaczony ciąg dla przypadku 0.
  • msgstr[N]: Przetłumaczony ciąg dla przypadku N.

Specyfikację pliku zamówienia zakupu można znaleźć tutaj.

Konfigurowanie obsługi plików zamówienia zakupu w programie ASP.NET Core

Ten przykład jest oparty na aplikacji ASP.NET Core MVC wygenerowanej na podstawie szablonu projektu programu Visual Studio 2019.

Odwoływanie się do pakietu

Dodaj odwołanie do OrchardCore.Localization.Core pakietu NuGet.

Plik .csproj zawiera teraz wiersz podobny do następującego (numer wersji może się różnić):

<PackageReference Include="OrchardCore.Localization.Core" Version="1.2.0" />

Rejestrowanie usługi

Dodaj wymagane usługi do ConfigureServices metody Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages()
        .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix);

    services.AddPortableObjectLocalization();

    services.Configure<RequestLocalizationOptions>(options => options
        .AddSupportedCultures("fr", "cs")
        .AddSupportedUICultures("fr", "cs")
    );
}

Dodaj wymagane oprogramowanie pośredniczące do Configure metody Startup.cs:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
    }

    app.UseRouting();
    app.UseStaticFiles();

    app.UseRequestLocalization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(name: "default", pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

Dodaj następujący kod do Razor wybranej strony. Index.cshtml jest używany w tym przykładzie.

@page
@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer
@{
    ViewData["Title"] = "Home";
}

<div class="text-center">
    <h1 class="display-4">Welcome</h1>
    <p>Learn about <a href="https://docs.microsoft.com/aspnet/core">building Web apps with ASP.NET Core</a>.</p>
</div>

<p>@Localizer["Hello world!"]</p>

Wystąpienie IViewLocalizer jest wstrzykiwane i używane do tłumaczenia tekstu "Hello world!".

Tworzenie pliku zamówienia zakupu

Utwórz plik o nazwie <culture code.po> w folderze głównym aplikacji. W tym przykładzie nazwa pliku to fr.po , ponieważ jest używany język francuski:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Ten plik przechowuje zarówno ciąg do tłumaczenia, jak i przetłumaczony po francusku ciąg. Tłumaczenia wracają do ich kultury nadrzędnej, jeśli to konieczne. W tym przykładzie plik fr.po jest używany, jeśli żądana kultura to fr-FR lub fr-CA.

Testowanie aplikacji

Uruchom aplikację i przejdź do adresu URL /Index. Zostanie wyświetlony tekst Hello world!

Przejdź pod adres URL /Index?culture=fr-FR. Zostanie wyświetlony tekst Bonjour le monde!

Pluralizacja

Pliki zamówienia zakupu obsługują formularze pluralizacji, co jest przydatne, gdy ten sam ciąg musi być tłumaczony inaczej na podstawie kardynalności. To zadanie jest skomplikowane przez fakt, że każdy język definiuje reguły niestandardowe, aby wybrać ciąg do użycia na podstawie kardynalności.

Pakiet Lokalizacji Sad udostępnia interfejs API do automatycznego wywoływania tych różnych formularzy w liczbie mnogiej.

Tworzenie plików zamówienia zakupu w liczbie mnogiej

Dodaj następującą zawartość do wcześniej wymienionego pliku fr.po :

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."

Zobacz Co to jest plik zamówienia zakupu? aby uzyskać wyjaśnienie, co reprezentuje każdy wpis w tym przykładzie.

Dodawanie języka przy użyciu różnych formularzy mnogiej

W poprzednim przykładzie użyto ciągów angielskich i francuskich. Angielski i francuski mają tylko dwie formy liczby mnogiej i mają te same reguły formularza, co oznacza, że kardynalność jednego jest mapowana na pierwszą formę mnogią. Każda inna kardynalność jest mapowana na drugą postać mnogią.

Nie wszystkie języki mają te same reguły. Jest to zilustrowane językiem czeskim, który ma trzy formy mnogiej.

cs.po Utwórz plik w następujący sposób i zwróć uwagę, jak liczba mnogiej wymaga trzech różnych tłumaczeń:

msgid "Hello world!"
msgstr "Ahoj světe!!"

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Existuje jedna položka."
msgstr[1] "Existují {0} položky."
msgstr[2] "Existuje {0} položek."

Aby zaakceptować czeskie lokalizacje, dodaj "cs" do listy obsługiwanych kultur w metodzie ConfigureServices :

services.Configure<RequestLocalizationOptions>(options => options
                .AddSupportedCultures("fr", "cs")
                .AddSupportedUICultures("fr", "cs")
            );

Edytuj plik w celu renderowania Pages/Index.cshtml zlokalizowanych ciągów w liczbie mnogiej dla kilku kardynalizacji:

<p>@Localizer.Plural(1, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(2, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(5, "There is one item.", "There are {0} items.")</p>

Uwaga: W rzeczywistym scenariuszu zmienna będzie używana do reprezentowania liczby. W tym miejscu powtarzamy ten sam kod z trzema różnymi wartościami, aby uwidocznić bardzo konkretny przypadek.

Po przełączeniu kultur zobaczysz następujące elementy:

W przypadku wersji /Index:

There is one item.
There are 2 items.
There are 5 items.

W przypadku wersji /Index?culture=fr:

Il y a un élément.
Il y a 2 éléments.
Il y a 5 éléments.

W przypadku wersji /Index?culture=cs:

Existuje jedna položka.
Existují 2 položky.
Existuje 5 položek.

Należy pamiętać, że w przypadku kultury czeskiej trzy tłumaczenia są różne. Kultury francuskie i angielskie mają tę samą konstrukcję dla dwóch ostatnich przetłumaczonych ciągów.

Zaawansowane zadania

Kontekstowe ciągi

Aplikacje często zawierają ciągi, które mają być tłumaczone w kilku miejscach. Ten sam ciąg może mieć inne tłumaczenie w niektórych lokalizacjach w aplikacji (Razor widoki lub pliki klas). Plik zamówienia zakupu obsługuje pojęcie kontekstu pliku, który może służyć do kategoryzowania reprezentowanego ciągu. Przy użyciu kontekstu pliku ciąg może być tłumaczony inaczej, w zależności od kontekstu pliku (lub braku kontekstu pliku).

Usługi lokalizacji zamówienia zakupu używają nazwy pełnej klasy lub widoku używanego podczas tłumaczenia ciągu. Jest to realizowane przez ustawienie wartości wpisu msgctxt .

Rozważ drobny dodatek do poprzedniego przykładu fr.po . Razor Widok znajdujący się w Pages/Index.cshtml lokalizacji można zdefiniować jako kontekst pliku, ustawiając wartość wpisu zarezerwowanegomsgctxt:

msgctxt "Pages.Index"
msgid "Hello world!"
msgstr "Bonjour le monde!"

Gdy zestaw jest taki msgctxt , tłumaczenie tekstu odbywa się podczas przechodzenia do /Index?culture=fr-FRelementu . Tłumaczenie nie zostanie wykonane podczas przechodzenia do /Privacy?culture=fr-FRelementu .

Jeśli żaden konkretny wpis nie jest zgodny z danym kontekstem pliku, mechanizm rezerwowy Sad Core szuka odpowiedniego pliku zamówienia zakupu bez kontekstu. Przy założeniu, że nie zdefiniowano określonego kontekstu pliku dla Pages/Privacy.cshtmlprogramu , nawigowanie po /Privacy?culture=fr-FR załadowaniu pliku zamówienia zakupu, takiego jak:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Zmienianie lokalizacji plików zamówienia zakupu

Domyślną lokalizację plików zamówienia zakupu można zmienić w pliku ConfigureServices:

services.AddPortableObjectLocalization(options => options.ResourcesPath = "Localization");

W tym przykładzie pliki zamówienia zakupu są ładowane z folderu Lokalizacja .

Implementowanie niestandardowej logiki do znajdowania plików lokalizacji

Gdy potrzebna jest bardziej złożona logika w celu zlokalizowania plików zamówienia zakupu, OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider interfejs można zaimplementować i zarejestrować jako usługę. Jest to przydatne, gdy pliki zamówienia zakupu mogą być przechowywane w różnych lokalizacjach lub gdy pliki muszą być znalezione w hierarchii folderów.

Używanie innego domyślnego języka w liczbie mnogiej

Pakiet zawiera metodę rozszerzenia specyficzną Plural dla dwóch form w liczbie mnogiej. W przypadku języków wymagających większej liczby formularzy w liczbie mnogiej utwórz metodę rozszerzenia. W przypadku metody rozszerzenia nie trzeba podawać żadnego pliku lokalizacji dla języka domyślnego — oryginalne ciągi są już dostępne bezpośrednio w kodzie.

Można użyć bardziej ogólnego Plural(int count, string[] pluralForms, params object[] arguments) przeciążenia, które akceptuje tablicę ciągów tłumaczeń.

Przez Sébastien Ros, Scott Addie i Hisham Bin Ateya

W tym artykule przedstawiono procedurę używania plików obiektów przenośnych (PO) w aplikacji ASP.NET Core z platformą Sad Core .

Uwaga: Sad Core nie jest produktem firmy Microsoft. W związku z tym firma Microsoft nie zapewnia pomocy technicznej dla tej funkcji.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Co to jest plik zamówienia zakupu?

Pliki zamówienia zakupu są dystrybuowane jako pliki tekstowe zawierające przetłumaczone ciągi dla danego języka. Niektóre zalety używania plików zamówienia zakupu zamiast plików resx obejmują:

  • Pliki zamówienia zakupu obsługują mnogią; Pliki resx nie obsługują liczby mnogiej.
  • Pliki zamówienia zakupu nie są kompilowane, takie jak pliki resx . W związku z tym wyspecjalizowane narzędzia i kroki kompilacji nie są wymagane.
  • Pliki zamówienia zakupu działają dobrze z narzędziami do wspólnego edytowania online.

Przykład

Oto przykładowy plik zamówienia zakupu zawierający tłumaczenie dwóch ciągów w języku francuskim, w tym jeden z jego postacią mnogią:

fr.po

#: Services/EmailService.cs:29
msgid "Enter a comma separated list of email addresses."
msgstr "Entrez une liste d'emails séparés par une virgule."

#: Views/Email.cshtml:112
msgid "The email address is \"{0}\"."
msgid_plural "The email addresses are \"{0}\"."
msgstr[0] "L'adresse email est \"{0}\"."
msgstr[1] "Les adresses email sont \"{0}\""

W tym przykładzie użyto następującej składni:

  • #:: komentarz wskazujący kontekst ciągu, który ma zostać przetłumaczony. Ten sam ciąg może być tłumaczony inaczej w zależności od tego, gdzie jest używany.
  • msgid: nieprzetłumaczony ciąg.
  • msgstr: przetłumaczony ciąg.

W przypadku obsługi liczby mnogiej można zdefiniować więcej wpisów.

  • msgid_plural: nieprzetłumaczony ciąg w liczbie mnogiej.
  • msgstr[0]: przetłumaczony ciąg dla przypadku 0.
  • msgstr[N]: Przetłumaczony ciąg dla przypadku N.

Specyfikację pliku zamówienia zakupu można znaleźć tutaj.

Konfigurowanie obsługi plików zamówienia zakupu w programie ASP.NET Core

Ten przykład jest oparty na aplikacji ASP.NET Core MVC wygenerowanej na podstawie szablonu projektu programu Visual Studio 2017.

Odwoływanie się do pakietu

Dodaj odwołanie do OrchardCore.Localization.Core pakietu NuGet.

Plik .csproj zawiera teraz wiersz podobny do następującego (numer wersji może się różnić):

<PackageReference Include="OrchardCore.Localization.Core" Version="1.0.0" />

Rejestrowanie usługi

Dodaj wymagane usługi do ConfigureServices metody Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix);

    services.AddPortableObjectLocalization();

    services.Configure<RequestLocalizationOptions>(options =>
        {
            var supportedCultures = new List<CultureInfo>
            {
                new CultureInfo("en-US"),
                new CultureInfo("en"),
                new CultureInfo("fr-FR"),
                new CultureInfo("fr")
            };

            options.DefaultRequestCulture = new RequestCulture("en-US");
            options.SupportedCultures = supportedCultures;
            options.SupportedUICultures = supportedCultures;
        });
}

Dodaj wymagane oprogramowanie pośredniczące do Configure metody Startup.cs:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
    }

    app.UseRouting();
    app.UseStaticFiles();

    app.UseRequestLocalization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(name: "default", pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

Dodaj następujący kod do Razor wybranego widoku. About.cshtml jest używany w tym przykładzie.

@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer

<p>@Localizer["Hello world!"]</p>

Wystąpienie IViewLocalizer jest wstrzykiwane i używane do tłumaczenia tekstu "Hello world!".

Tworzenie pliku zamówienia zakupu

Utwórz plik o nazwie <culture code.po> w folderze głównym aplikacji. W tym przykładzie nazwa pliku to fr.po , ponieważ jest używany język francuski:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Ten plik przechowuje zarówno ciąg do tłumaczenia, jak i przetłumaczony po francusku ciąg. Tłumaczenia wracają do ich kultury nadrzędnej, jeśli to konieczne. W tym przykładzie plik fr.po jest używany, jeśli żądana kultura to fr-FR lub fr-CA.

Testowanie aplikacji

Uruchom aplikację i przejdź do adresu URL /Home/About. Zostanie wyświetlony tekst Hello world!

Przejdź pod adres URL /Home/About?culture=fr-FR. Zostanie wyświetlony tekst Bonjour le monde!

Pluralizacja

Pliki zamówienia zakupu obsługują formularze pluralizacji, co jest przydatne, gdy ten sam ciąg musi być tłumaczony inaczej na podstawie kardynalności. To zadanie jest skomplikowane przez fakt, że każdy język definiuje reguły niestandardowe, aby wybrać ciąg do użycia na podstawie kardynalności.

Pakiet Lokalizacji Sad udostępnia interfejs API do automatycznego wywoływania tych różnych formularzy w liczbie mnogiej.

Tworzenie plików zamówienia zakupu w liczbie mnogiej

Dodaj następującą zawartość do wcześniej wymienionego pliku fr.po :

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."

Zobacz Co to jest plik zamówienia zakupu? aby uzyskać wyjaśnienie, co reprezentuje każdy wpis w tym przykładzie.

Dodawanie języka przy użyciu różnych formularzy mnogiej

W poprzednim przykładzie użyto ciągów angielskich i francuskich. Angielski i francuski mają tylko dwie formy liczby mnogiej i mają te same reguły formularza, co oznacza, że kardynalność jednego jest mapowana na pierwszą formę mnogią. Każda inna kardynalność jest mapowana na drugą postać mnogią.

Nie wszystkie języki mają te same reguły. Jest to zilustrowane językiem czeskim, który ma trzy formy mnogiej.

cs.po Utwórz plik w następujący sposób i zwróć uwagę, jak liczba mnogiej wymaga trzech różnych tłumaczeń:

msgid "Hello world!"
msgstr "Ahoj světe!!"

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Existuje jedna položka."
msgstr[1] "Existují {0} položky."
msgstr[2] "Existuje {0} položek."

Aby zaakceptować czeskie lokalizacje, dodaj "cs" do listy obsługiwanych kultur w metodzie ConfigureServices :

var supportedCultures = new List<CultureInfo>
{
    new CultureInfo("en-US"),
    new CultureInfo("en"),
    new CultureInfo("fr-FR"),
    new CultureInfo("fr"),
    new CultureInfo("cs")
};

Edytuj plik w celu renderowania Views/Home/About.cshtml zlokalizowanych ciągów w liczbie mnogiej dla kilku kardynalizacji:

<p>@Localizer.Plural(1, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(2, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(5, "There is one item.", "There are {0} items.")</p>

Uwaga: W rzeczywistym scenariuszu zmienna będzie używana do reprezentowania liczby. W tym miejscu powtarzamy ten sam kod z trzema różnymi wartościami, aby uwidocznić bardzo konkretny przypadek.

Po przełączeniu kultur zobaczysz następujące elementy:

W przypadku wersji /Home/About:

There is one item.
There are 2 items.
There are 5 items.

W przypadku wersji /Home/About?culture=fr:

Il y a un élément.
Il y a 2 éléments.
Il y a 5 éléments.

W przypadku wersji /Home/About?culture=cs:

Existuje jedna položka.
Existují 2 položky.
Existuje 5 položek.

Należy pamiętać, że w przypadku kultury czeskiej trzy tłumaczenia są różne. Kultury francuskie i angielskie mają tę samą konstrukcję dla dwóch ostatnich przetłumaczonych ciągów.

Zaawansowane zadania

Kontekstowe ciągi

Aplikacje często zawierają ciągi, które mają być tłumaczone w kilku miejscach. Ten sam ciąg może mieć inne tłumaczenie w niektórych lokalizacjach w aplikacji (Razor widoki lub pliki klas). Plik zamówienia zakupu obsługuje pojęcie kontekstu pliku, który może służyć do kategoryzowania reprezentowanego ciągu. Przy użyciu kontekstu pliku ciąg może być tłumaczony inaczej, w zależności od kontekstu pliku (lub braku kontekstu pliku).

Usługi lokalizacji zamówienia zakupu używają nazwy pełnej klasy lub widoku używanego podczas tłumaczenia ciągu. Jest to realizowane przez ustawienie wartości wpisu msgctxt .

Rozważ drobny dodatek do poprzedniego przykładu fr.po . Razor Widok znajdujący się w Views/Home/About.cshtml lokalizacji można zdefiniować jako kontekst pliku, ustawiając wartość wpisu zarezerwowanegomsgctxt:

msgctxt "Views.Home.About"
msgid "Hello world!"
msgstr "Bonjour le monde!"

Gdy zestaw jest taki msgctxt , tłumaczenie tekstu odbywa się podczas przechodzenia do /Home/About?culture=fr-FRelementu . Tłumaczenie nie zostanie wykonane podczas przechodzenia do /Home/Contact?culture=fr-FRelementu .

Jeśli żaden konkretny wpis nie jest zgodny z danym kontekstem pliku, mechanizm rezerwowy Sad Core szuka odpowiedniego pliku zamówienia zakupu bez kontekstu. Przy założeniu, że nie zdefiniowano określonego kontekstu pliku dla Views/Home/Contact.cshtmlprogramu , nawigowanie po /Home/Contact?culture=fr-FR załadowaniu pliku zamówienia zakupu, takiego jak:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Zmienianie lokalizacji plików zamówienia zakupu

Domyślną lokalizację plików zamówienia zakupu można zmienić w pliku ConfigureServices:

services.AddPortableObjectLocalization(options => options.ResourcesPath = "Localization");

W tym przykładzie pliki zamówienia zakupu są ładowane z folderu Lokalizacja .

Implementowanie niestandardowej logiki do znajdowania plików lokalizacji

Gdy potrzebna jest bardziej złożona logika w celu zlokalizowania plików zamówienia zakupu, OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider interfejs można zaimplementować i zarejestrować jako usługę. Jest to przydatne, gdy pliki zamówienia zakupu mogą być przechowywane w różnych lokalizacjach lub gdy pliki muszą być znalezione w hierarchii folderów.

Używanie innego domyślnego języka w liczbie mnogiej

Pakiet zawiera metodę rozszerzenia specyficzną Plural dla dwóch form w liczbie mnogiej. W przypadku języków wymagających większej liczby formularzy w liczbie mnogiej utwórz metodę rozszerzenia. W przypadku metody rozszerzenia nie trzeba podawać żadnego pliku lokalizacji dla języka domyślnego — oryginalne ciągi są już dostępne bezpośrednio w kodzie.

Można użyć bardziej ogólnego Plural(int count, string[] pluralForms, params object[] arguments) przeciążenia, które akceptuje tablicę ciągów tłumaczeń.