Condividi tramite

Configurare la localizzazione degli oggetti portabili in ASP.NET Core

  • Articolo

Di Hisham Bin Ateya e Sébastien Ros.

Questo articolo descrive i passaggi per l'uso dei file degli oggetti portabili (Portable Object, PO) in un'applicazione ASP.NET Core con il framework Orchard Core.

Nota: Orchard Core non è un prodotto Microsoft. Microsoft non fornisce supporto per questa funzionalità.

Visualizzare o scaricare il codice di esempio (procedura per il download)

Che cos'è un file PO?

I file PO sono distribuiti come file di testo contenenti le stringhe tradotte per una determinata lingua. Alcuni vantaggi dell'uso dei file PO invece dei file resx includono:

  • Pluralizzazione del supporto dei file PO; i file .resx non supportano la pluralizzazione.
  • I file PO non vengono compilati come i file .resx. Di conseguenza, non sono richiesti strumenti e passaggi di compilazione specifici.
  • I file PO funzionano perfettamente con gli strumenti di modifica online di collaborazione.

Esempio

Il file po di esempio seguente contiene la traduzione per due stringhe in francese, inclusa una con il formato plurale:

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

Questo esempio usa la sintassi seguente:

  • #:: commento che indica il contesto della stringa da tradurre. La stessa stringa può essere tradotta in modo diverso a seconda della posizione in cui viene usata.
  • msgid: stringa non tradotta.
  • msgstr: stringa tradotta.

Per il supporto della pluralizzazione, è possibile definire più voci.

  • msgid_plural: stringa al plurale non tradotta.
  • msgstr[0]: stringa tradotta per il caso 0.
  • msgstr[N]: stringa tradotta per il caso N.

La specifica dei file PO è disponibile qui.

Configurazione del supporto dei file PO in ASP.NET Core

Questo esempio si basa su un'applicazione Web core ASP.NET generata da un modello di progetto di Visual Studio 2022.

Riferimento al pacchetto

Aggiungere un riferimento al pacchetto NuGet OrchardCore.Localization.Core.

Il .csproj file contiene ora una riga simile alla seguente (il numero di versione può variare):

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

Registrazione del servizio

Aggiungere i servizi necessari a Program.cs:

builder.Services.AddPortableObjectLocalization();

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

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

Aggiungere il codice seguente alla Razor pagina preferita. Index.cshtml viene usato in questo esempio.

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

Viene inserita un'istanza IViewLocalizer che viene usata per tradurre il testo "Hello world!".

Creazione di un file PO

Creare un file denominato <culture code.po> nella cartella radice dell'applicazione. In questo esempio il nome file è fr.po poiché viene usata la lingua francese:

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

Il file memorizza la stringa da tradurre e la stringa tradotta in francese. Le traduzioni vengono ripristinate alla relativa impostazione cultura, se necessario. In questo esempio viene usato il file fr.po se le impostazioni cultura richieste sono fr-FR o fr-CA.

Test dell'applicazione

Eseguire l'applicazione, viene visualizzato il testo Hello world! .

Accedi all'URL /Index?culture=fr-FR. Viene visualizzato il testo Bonjour le monde! .

Pluralizzazione

I file PO supportano le forme di pluralizzazione, utili quando è necessario tradurre la stessa stringa in modo diverso in base a una cardinalità. Questa attività risulta complessa poiché ogni lingua definisce regole personalizzate per la selezione della stringa da usare in base alla cardinalità.

Il pacchetto di localizzazione Orchard offre un'API per richiamare automaticamente le diverse forme plurali.

Creazione di file PO di pluralizzazione

Aggiungere il contenuto seguente al file fr.po indicato in precedenza:

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

Vedere Che cos'è un file PO? per una descrizione di ogni voce di questo esempio.

Aggiunta di una lingua che usa forme di pluralizzazione diverse

Nell'esempio precedente sono state usate stringhe in inglese e in francese. Inglese e francese hanno solo due forme di pluralizzazione e condividono le stesse regole di formato, ovvero una cardinalità viene mappata alla prima forma plurale. Un'eventuale altra cardinalità viene mappata alla seconda forma plurale.

Non tutte le lingue condividono le stesse regole. La lingua ceca, ad esempio, ha tre forme plurali.

Creare il file cs.po come descritto di seguito e notare che la pluralizzazione richiede tre traduzioni diverse:

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

Per accettare le localizzazioni ceche, aggiungere "cs" all'elenco delle impostazioni cultura supportate nel metodo Configure:

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

Modificare il file per eseguire il Pages/Index.cshtml rendering di stringhe plurali localizzate per diverse cardinalità:

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

Nota: in uno scenario reale potrebbe essere usata una variabile per rappresentare il conteggio. In questo caso si ripete lo stesso codice con tre valori diversi per esporre un caso specifico.

Per le diverse impostazioni cultura, si ottiene quanto segue:

Per /Index:

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

Per /Index?culture=fr:

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

Per /Index?culture=cs:

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

Per la cultura ceca, le tre traduzioni sono diverse. Le impostazioni cultura per la lingua inglese e francese condividono la stessa costruzione per le ultime due stringhe tradotte.

Attività avanzate

Uso di argomenti aggiuntivi

L'argomento in corrispondenza dell'indice zero {0} rappresenta sempre il valore count. Quando si richiama il Plural metodo è possibile aggiungere altri argomenti e il relativo indice inizierà da una (1).

<p>@Localizer.Plural(count, "There is one item with the color {1}.", "There are {0} items. The main color is {1}.", color)</p>

Contestualizzazione delle stringhe

Le applicazioni spesso contengono le stringhe da tradurre in posizioni diverse. La stessa stringa può avere una traduzione diversa in determinate posizioni all'interno di un'app (Razor visualizzazioni o file di classe). Un file PO supporta la nozione di contesto del file, che è possibile usare per categorizzare la stringa rappresentata. Usando un contesto di file è possibile tradurre una stringa in modo diverso a seconda del contesto o della mancanza del contesto.

I servizi di localizzazione PO usano il nome della classe completa o la visualizzazione usata durante la traduzione di una stringa. Questa operazione viene eseguita impostando il valore nella voce msgctxt.

Si supponga di eseguire un'aggiunta minore all'esempio fr.po precedente. Una Razor pagina che si trova in Pages/Index.cshtml può essere definita come contesto di file impostando il valore della voce riservata msgctxt :

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

Con msgctxt impostato in questo modo, la traduzione del testo si verifica quando si passa a /Index?culture=fr-FR. La traduzione non si verifica quando si passa a /Privacy?culture=fr-FR.

Quando nessuna voce corrisponde al contesto di file specificato, il meccanismo di fallback di Orchard Core cerca un file PO appropriato senza contesto. Supponendo che non esista un contesto di file specifico definito per Pages/Privacy.cshtml, passare a /Privacy?culture=fr-FR carica un file po di acquisto, ad esempio:

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

Modifica della posizione dei file PO

La posizione predefinita dei file PO può essere modificata in Programs.cs:

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

In questo esempio i file PO vengono caricati dalla cartella Localization.

Implementazione di una logica personalizzata per la ricerca dei file di localizzazione

Quando è necessaria una logica più complessa per individuare i file PO, l'interfaccia OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider può essere implementata e registrata come servizio. Ciò è utile quando i file PO possono essere memorizzati in posizioni diverse o quando i file devono essere cercati all'interno di una gerarchia di cartelle.

Uso di una lingua pluralizzata predefinita diversa

Il pacchetto include un metodo di estensione Plural specifico di due forme plurali. Per le lingue che richiedono ulteriori forme plurali, creare un metodo di estensione. Con un metodo di estensione non è necessario fornire alcun file di localizzazione per la lingua predefinita. Le stringhe originali sono già disponibili direttamente nel codice.

È possibile usare l'overload Plural(int count, string[] pluralForms, params object[] arguments) più generico che accetta una matrice di stringhe di traduzioni.

Di Sébastien Ros, Scott Addie e Hisham Bin Ateya

Questo articolo descrive i passaggi per l'uso dei file degli oggetti portabili (Portable Object, PO) in un'applicazione ASP.NET Core con il framework Orchard Core.

Nota: Orchard Core non è un prodotto Microsoft. Di conseguenza, Microsoft non fornisce alcun supporto per questa funzionalità.

Visualizzare o scaricare il codice di esempio (procedura per il download)

Che cos'è un file PO?

I file PO sono distribuiti come file di testo contenenti le stringhe tradotte per una determinata lingua. Alcuni vantaggi dell'uso dei file PO invece dei file resx includono:

  • Pluralizzazione del supporto dei file PO; i file .resx non supportano la pluralizzazione.
  • I file PO non vengono compilati come i file .resx. Di conseguenza, non sono richiesti strumenti e passaggi di compilazione specifici.
  • I file PO funzionano perfettamente con gli strumenti di modifica online di collaborazione.

Esempio

Di seguito è riportato un file PO di esempio contenente le traduzioni di due stringhe in francese, inclusa la stringa con la forma plurale:

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

Questo esempio usa la sintassi seguente:

  • #:: commento che indica il contesto della stringa da tradurre. La stessa stringa può essere tradotta in modo diverso a seconda della posizione in cui viene usata.
  • msgid: stringa non tradotta.
  • msgstr: stringa tradotta.

Se è supportata la pluralizzazione, è possibile definire più voci.

  • msgid_plural: stringa al plurale non tradotta.
  • msgstr[0]: stringa tradotta per il caso 0.
  • msgstr[N]: stringa tradotta per il caso N.

La specifica dei file PO è disponibile qui.

Configurazione del supporto dei file PO in ASP.NET Core

Questo esempio si basa su un'applicazione MVC core ASP.NET generata da un modello di progetto di Visual Studio 2019.

Riferimento al pacchetto

Aggiungere un riferimento al pacchetto NuGet OrchardCore.Localization.Core.

Il .csproj file contiene ora una riga simile alla seguente (il numero di versione può variare):

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

Registrazione del servizio

Aggiungere i servizi necessari al ConfigureServices metodo di 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")
    );
}

Aggiungere il middleware necessario al Configure metodo di 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?}");
    });
}

Aggiungere il codice seguente alla Razor pagina preferita. Index.cshtml viene usato in questo esempio.

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

Viene inserita un'istanza IViewLocalizer che viene usata per tradurre il testo "Hello world!".

Creazione di un file PO

Creare un file denominato <culture code.po> nella cartella radice dell'applicazione. In questo esempio il nome file è fr.po poiché viene usata la lingua francese:

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

Il file memorizza la stringa da tradurre e la stringa tradotta in francese. Le traduzioni vengono ripristinate alla relativa impostazione cultura, se necessario. In questo esempio viene usato il file fr.po se le impostazioni cultura richieste sono fr-FR o fr-CA.

Test dell'applicazione

Eseguire l'applicazione e passare all'URL /Index. Viene visualizzato il testo Hello world! .

Accedi all'URL /Index?culture=fr-FR. Viene visualizzato il testo Bonjour le monde! .

Pluralizzazione

I file PO supportano le forme di pluralizzazione, utili quando è necessario tradurre la stessa stringa in modo diverso in base a una cardinalità. Questa attività risulta complessa poiché ogni lingua definisce regole personalizzate per la selezione della stringa da usare in base alla cardinalità.

Il pacchetto di localizzazione Orchard offre un'API per richiamare automaticamente le diverse forme plurali.

Creazione di file PO di pluralizzazione

Aggiungere il contenuto seguente al file fr.po indicato in precedenza:

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

Vedere Che cos'è un file PO? per una descrizione di ogni voce di questo esempio.

Aggiunta di una lingua che usa forme di pluralizzazione diverse

Nell'esempio precedente sono state usate stringhe in inglese e in francese. Inglese e francese hanno solo due forme di pluralizzazione e condividono le stesse regole di formato, ovvero una cardinalità viene mappata alla prima forma plurale. Un'eventuale altra cardinalità viene mappata alla seconda forma plurale.

Non tutte le lingue condividono le stesse regole. La lingua ceca, ad esempio, ha tre forme plurali.

Creare il file cs.po come descritto di seguito e notare che la pluralizzazione richiede tre traduzioni diverse:

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

Per accettare le localizzazioni ceche, aggiungere "cs" all'elenco delle impostazioni cultura supportate nel metodo ConfigureServices:

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

Modificare il file per eseguire il Pages/Index.cshtml rendering di stringhe plurali localizzate per diverse cardinalità:

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

Nota: in uno scenario reale potrebbe essere usata una variabile per rappresentare il conteggio. In questo caso, viene ripetuto lo stesso codice con tre valori diversi per esporre un caso molto specifico.

Per le diverse impostazioni cultura, si ottiene quanto segue:

Per /Index:

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

Per /Index?culture=fr:

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

Per /Index?culture=cs:

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

Si noti che per le impostazioni cultura per la lingua ceca, le tre traduzioni sono diverse. Le impostazioni cultura per la lingua inglese e francese condividono la stessa costruzione per le ultime due stringhe tradotte.

Attività avanzate

Contestualizzazione delle stringhe

Le applicazioni spesso contengono le stringhe da tradurre in posizioni diverse. La stessa stringa può avere una traduzione diversa in determinate posizioni all'interno di un'app (Razor visualizzazioni o file di classe). Un file PO supporta la nozione di contesto del file, che è possibile usare per categorizzare la stringa rappresentata. Usando un contesto di file è possibile tradurre una stringa in modo diverso a seconda del contesto o della mancanza del contesto.

I servizi di localizzazione PO usano il nome della classe completa o la visualizzazione usata durante la traduzione di una stringa. Questa operazione viene eseguita impostando il valore nella voce msgctxt.

Si supponga di eseguire un'aggiunta minore all'esempio fr.po precedente. Una Razor vista che si trova in Pages/Index.cshtml può essere definita come contesto di file impostando il valore della voce riservata msgctxt :

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

Con msgctxt impostato in questo modo, la traduzione del testo si verifica quando si passa a /Index?culture=fr-FR. La traduzione non si verifica quando si passa a /Privacy?culture=fr-FR.

Quando nessuna voce corrisponde al contesto di file specificato, il meccanismo di fallback di Orchard Core cerca un file PO appropriato senza contesto. Supponendo che non esista un contesto di file specifico definito per Pages/Privacy.cshtml, passare a /Privacy?culture=fr-FR carica un file po di acquisto, ad esempio:

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

Modifica della posizione dei file PO

La posizione predefinita dei file PO può essere modificata in ConfigureServices:

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

In questo esempio i file PO vengono caricati dalla cartella Localization.

Implementazione di una logica personalizzata per la ricerca dei file di localizzazione

Quando è necessaria una logica più complessa per individuare i file PO, l'interfaccia OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider può essere implementata e registrata come servizio. Ciò è utile quando i file PO possono essere memorizzati in posizioni diverse o quando i file devono essere cercati all'interno di una gerarchia di cartelle.

Uso di una lingua pluralizzata predefinita diversa

Il pacchetto include un metodo di estensione Plural specifico di due forme plurali. Per le lingue che richiedono ulteriori forme plurali, creare un metodo di estensione. Con un metodo di estensione non è necessario fornire alcun file di localizzazione per la lingua predefinita. Le stringhe originali sono già disponibili direttamente nel codice.

È possibile usare l'overload Plural(int count, string[] pluralForms, params object[] arguments) più generico che accetta una matrice di stringhe di traduzioni.

Di Sébastien Ros, Scott Addie e Hisham Bin Ateya

Questo articolo descrive i passaggi per l'uso dei file degli oggetti portabili (Portable Object, PO) in un'applicazione ASP.NET Core con il framework Orchard Core.

Nota: Orchard Core non è un prodotto Microsoft. Di conseguenza, Microsoft non fornisce alcun supporto per questa funzionalità.

Visualizzare o scaricare il codice di esempio (procedura per il download)

Che cos'è un file PO?

I file PO sono distribuiti come file di testo contenenti le stringhe tradotte per una determinata lingua. Alcuni vantaggi dell'uso dei file PO invece dei file resx includono:

  • Pluralizzazione del supporto dei file PO; i file .resx non supportano la pluralizzazione.
  • I file PO non vengono compilati come i file .resx. Di conseguenza, non sono richiesti strumenti e passaggi di compilazione specifici.
  • I file PO funzionano perfettamente con gli strumenti di modifica online di collaborazione.

Esempio

Di seguito è riportato un file PO di esempio contenente le traduzioni di due stringhe in francese, inclusa la stringa con la forma plurale:

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}\""

Questo esempio usa la sintassi seguente:

  • #:: commento che indica il contesto della stringa da tradurre. La stessa stringa può essere tradotta in modo diverso a seconda della posizione in cui viene usata.
  • msgid: stringa non tradotta.
  • msgstr: stringa tradotta.

Se è supportata la pluralizzazione, è possibile definire più voci.

  • msgid_plural: stringa al plurale non tradotta.
  • msgstr[0]: stringa tradotta per il caso 0.
  • msgstr[N]: stringa tradotta per il caso N.

La specifica dei file PO è disponibile qui.

Configurazione del supporto dei file PO in ASP.NET Core

Questo esempio è basato su un'applicazione ASP.NET Core MVC generata da un modello di progetto Visual Studio 2017.

Riferimento al pacchetto

Aggiungere un riferimento al pacchetto NuGet OrchardCore.Localization.Core.

Il .csproj file contiene ora una riga simile alla seguente (il numero di versione può variare):

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

Registrazione del servizio

Aggiungere i servizi necessari al ConfigureServices metodo di 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;
        });
}

Aggiungere il middleware necessario al Configure metodo di 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?}");
    });
}

Aggiungere il codice seguente alla Razor visualizzazione desiderata. About.cshtml viene usato in questo esempio.

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

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

Viene inserita un'istanza IViewLocalizer che viene usata per tradurre il testo "Hello world!".

Creazione di un file PO

Creare un file denominato <culture code.po> nella cartella radice dell'applicazione. In questo esempio il nome file è fr.po poiché viene usata la lingua francese:

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

Il file memorizza la stringa da tradurre e la stringa tradotta in francese. Le traduzioni vengono ripristinate alla relativa impostazione cultura, se necessario. In questo esempio viene usato il file fr.po se le impostazioni cultura richieste sono fr-FR o fr-CA.

Test dell'applicazione

Eseguire l'applicazione e passare all'URL /Home/About. Viene visualizzato il testo Hello world! .

Accedi all'URL /Home/About?culture=fr-FR. Viene visualizzato il testo Bonjour le monde! .

Pluralizzazione

I file PO supportano le forme di pluralizzazione, utili quando è necessario tradurre la stessa stringa in modo diverso in base a una cardinalità. Questa attività risulta complessa poiché ogni lingua definisce regole personalizzate per la selezione della stringa da usare in base alla cardinalità.

Il pacchetto di localizzazione Orchard offre un'API per richiamare automaticamente le diverse forme plurali.

Creazione di file PO di pluralizzazione

Aggiungere il contenuto seguente al file fr.po indicato in precedenza:

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

Vedere Che cos'è un file PO? per una descrizione di ogni voce di questo esempio.

Aggiunta di una lingua che usa forme di pluralizzazione diverse

Nell'esempio precedente sono state usate stringhe in inglese e in francese. Inglese e francese hanno solo due forme di pluralizzazione e condividono le stesse regole di formato, ovvero una cardinalità viene mappata alla prima forma plurale. Un'eventuale altra cardinalità viene mappata alla seconda forma plurale.

Non tutte le lingue condividono le stesse regole. La lingua ceca, ad esempio, ha tre forme plurali.

Creare il file cs.po come descritto di seguito e notare che la pluralizzazione richiede tre traduzioni diverse:

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

Per accettare le localizzazioni ceche, aggiungere "cs" all'elenco delle impostazioni cultura supportate nel metodo ConfigureServices:

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

Modificare il file per eseguire il Views/Home/About.cshtml rendering di stringhe plurali localizzate per diverse cardinalità:

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

Nota: in uno scenario reale potrebbe essere usata una variabile per rappresentare il conteggio. In questo caso, viene ripetuto lo stesso codice con tre valori diversi per esporre un caso molto specifico.

Per le diverse impostazioni cultura, si ottiene quanto segue:

Per /Home/About:

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

Per /Home/About?culture=fr:

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

Per /Home/About?culture=cs:

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

Si noti che per le impostazioni cultura per la lingua ceca, le tre traduzioni sono diverse. Le impostazioni cultura per la lingua inglese e francese condividono la stessa costruzione per le ultime due stringhe tradotte.

Attività avanzate

Contestualizzazione delle stringhe

Le applicazioni spesso contengono le stringhe da tradurre in posizioni diverse. La stessa stringa può avere una traduzione diversa in determinate posizioni all'interno di un'app (Razor visualizzazioni o file di classe). Un file PO supporta la nozione di contesto del file, che è possibile usare per categorizzare la stringa rappresentata. Usando un contesto di file è possibile tradurre una stringa in modo diverso a seconda del contesto o della mancanza del contesto.

I servizi di localizzazione PO usano il nome della classe completa o la visualizzazione usata durante la traduzione di una stringa. Questa operazione viene eseguita impostando il valore nella voce msgctxt.

Si supponga di eseguire un'aggiunta minore all'esempio fr.po precedente. Una Razor vista che si trova in Views/Home/About.cshtml può essere definita come contesto di file impostando il valore della voce riservata msgctxt :

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

Con msgctxt impostato in questo modo, la traduzione del testo si verifica quando si passa a /Home/About?culture=fr-FR. La traduzione non si verifica quando si passa a /Home/Contact?culture=fr-FR.

Quando nessuna voce corrisponde al contesto di file specificato, il meccanismo di fallback di Orchard Core cerca un file PO appropriato senza contesto. Supponendo che non esista un contesto di file specifico definito per Views/Home/Contact.cshtml, passare a /Home/Contact?culture=fr-FR carica un file po di acquisto, ad esempio:

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

Modifica della posizione dei file PO

La posizione predefinita dei file PO può essere modificata in ConfigureServices:

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

In questo esempio i file PO vengono caricati dalla cartella Localization.

Implementazione di una logica personalizzata per la ricerca dei file di localizzazione

Quando è necessaria una logica più complessa per individuare i file PO, l'interfaccia OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider può essere implementata e registrata come servizio. Ciò è utile quando i file PO possono essere memorizzati in posizioni diverse o quando i file devono essere cercati all'interno di una gerarchia di cartelle.

Uso di una lingua pluralizzata predefinita diversa

Il pacchetto include un metodo di estensione Plural specifico di due forme plurali. Per le lingue che richiedono ulteriori forme plurali, creare un metodo di estensione. Con un metodo di estensione non è necessario fornire alcun file di localizzazione per la lingua predefinita. Le stringhe originali sono già disponibili direttamente nel codice.

È possibile usare l'overload Plural(int count, string[] pluralForms, params object[] arguments) più generico che accetta una matrice di stringhe di traduzioni.