Configurer la localisation d’objets portables dans ASP.NET Core
Par Hisham Bin Ateya et Sébastien Ros.
Cet article présente les étapes d’utilisation d’objets portables (PO, Portable Object) dans une application ASP.NET Core avec le framework Orchard Core.
Remarque : Orchard Core n’est pas un produit Microsoft. Microsoft ne fournit aucun support pour cette fonctionnalité.
Affichez ou téléchargez l’exemple de code (procédure de téléchargement)
Qu’est-ce qu’un fichier PO ?
Les fichiers PO sont distribués sous forme de fichiers texte contenant les chaînes traduites pour une langue donnée. L’utilisation de fichiers PO plutôt que des fichiers .resx présente certains avantages, notamment les suivants :
- Les fichiers PO prennent en charge la pluralisation, contrairement aux fichiers .resx.
- Les fichiers PO ne sont pas compilés comme les fichiers .resx. De ce fait, il n’est pas nécessaire d’effectuer les étapes relatives aux outils et à la génération.
- Les fichiers PO fonctionnent correctement avec les outils d’édition collaboratifs en ligne.
Exemple
L’exemple de fichier PO suivant contient la traduction de deux chaînes en français, dont une avec sa forme au pluriel :
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."
Cet exemple utilise la syntaxe suivante :
#:: commentaire indiquant le contexte de la chaîne à traduire. La même chaîne peut être traduite différemment selon l’endroit où elle est utilisée.msgid: la chaîne non traduite.msgstr: la chaîne traduite.
Des entrées supplémentaires peuvent être définies pour la prise en charge de la pluralisation.
msgid_plural: la chaîne au pluriel non traduite.msgstr[0]: la chaîne traduite pour le cas 0.msgstr[N]: la chaîne traduite pour le cas N.
La spécification du fichier PO se trouve ici.
Configuration de la prise en charge du fichier PO dans ASP.NET Core
Cet exemple est basé sur une application ASP.NET Core Web générée à partir d’un modèle de projet Visual Studio 2022.
Référencement du package
Ajoutez une référence au package NuGet OrchardCore.Localization.Core.
Le fichier .csproj contient maintenant une ligne semblable à la suivante (le numéro de version peut varier) :
<PackageReference Include="OrchardCore.Localization.Core" Version="1.5.0" />
Inscription du service
Ajoutez les services requis à Program.cs :
builder.Services.AddPortableObjectLocalization();
builder.Services
.Configure<RequestLocalizationOptions>(options => options
.AddSupportedCultures("fr", "cs")
.AddSupportedUICultures("fr", "cs"));
builder.Services
.AddRazorPages()
.AddViewLocalization();
Ajoutez le code suivant à la page Razor de votre choix. Index.cshtml est utilisé dans cet exemple.
@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>
Une instance IViewLocalizer est injectée et utilisée pour traduire le texte « Hello world! ».
Création d’un fichier PO
Créez un fichier nommé <code de culture>.po dans le dossier racine de votre application. Dans cet exemple, le nom de fichier est fr.po, car le français est utilisé :
msgid "Hello world!"
msgstr "Bonjour le monde!"
Ce fichier stocke à la fois la chaîne à traduire et la chaîne traduite en français. La culture parente des traductions peut être rétablie, si nécessaire. Dans cet exemple, le fichier fr.po est utilisé si la culture demandée est fr-FR ou fr-CA.
Test de l’application
Exécutez votre application, le texte Hello world! s’affiche.
Accédez à l’URL /Index?culture=fr-FR. Le texte Bonjour le monde ! s’affiche.
Forme plurielle
Les fichiers PO prennent en charge les formes de pluralisation, ce qui est utile quand la même chaîne doit être traduite différemment en fonction d’une cardinalité. Cette tâche est rendue compliquée par le fait que chaque langue définit des règles personnalisées pour sélectionner la chaîne à utiliser en fonction de la cardinalité.
Le package de localisation Orchard fournit une API pour appeler automatiquement ces différentes formes plurielles.
Création de fichiers PO de pluralisation
Ajoutez le contenu suivant au fichier fr.po mentionné précédemment :
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."
Consultez Qu’est-ce qu’un fichier PO ? pour obtenir une explication de ce que représente chaque entrée de cet exemple.
Ajout d’une langue utilisant différentes formes de pluralisation
Des chaînes en anglais et en français ont été utilisées dans l’exemple précédent. L’anglais et le français n’ont que deux formes de pluralisation et partagent les mêmes règles de forme, qui est qu’une cardinalité de 1 est mappée à la première forme plurielle. N’importe quelle autre cardinalité est mappée à la seconde forme plurielle.
Toutes les langues ne partagent pas les mêmes règles. À titre d’exemple, il y a la langue tchèque qui a trois formes plurielles.
Créez le fichier cs.po comme suit, puis notez comment la pluralisation a besoin de trois traductions différentes :
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."
Pour accepter les localisations tchèques, ajoutez "cs" à la liste des cultures prises en charge dans la méthode Configure :
builder.Services
.Configure<RequestLocalizationOptions>(options => options
.AddSupportedCultures("fr", "cs")
.AddSupportedUICultures("fr", "cs"));
Modifiez le fichier Pages/Index.cshtml pour restituer des chaînes localisées au pluriel pour plusieurs cardinalités :
<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>
Remarque : Dans un scénario réel, une variable serait utilisée pour représenter le nombre. Ici, nous répétons le même code avec trois valeurs différentes pour exposer un cas spécifique.
Quand vous passez d’une culture à l’autre, vous voyez ceci :
Pour /Index:
There is one item.
There are 2 items.
There are 5 items.
Pour /Index?culture=fr:
Il y a un élément.
Il y a 2 éléments.
Il y a 5 éléments.
Pour /Index?culture=cs:
Existuje jedna položka.
Existují 2 položky.
Existuje 5 položek.
Pour la culture tchèque, les trois traductions sont différentes. Les cultures anglaise et française partagent la même construction pour les deux dernières chaînes traduites.
Tâches avancées
Utiliser des arguments supplémentaires
L’argument à l’index zéro {0} représente toujours la valeur de comptage. Lors de l’appel de la méthode Plural, il est possible d’ajouter des arguments supplémentaires et leur index commence alors à un (1).
<p>@Localizer.Plural(count, "There is one item with the color {1}.", "There are {0} items. The main color is {1}.", color)</p>
Contextualisation de chaînes
Les applications contiennent souvent les chaînes à traduire dans plusieurs emplacements. La même chaîne peut avoir une traduction différente dans certains emplacements d’une application (vues Razor ou fichiers de classe). Un fichier PO prend en charge la notion d’un contexte de fichier, qui peut être utilisé pour catégoriser la chaîne représentée. L’utilisation d’un contexte de fichier permet de traduire une chaîne différemment en fonction du contexte du fichier (ou de l’absence de contexte de fichier).
Les services de localisation de PO utilisent le nom de la classe complète ou de la vue utilisée lors de la traduction d’une chaîne. Pour ce faire, il vous suffit de définir la valeur sur l’entrée msgctxt.
Examinons un ajout mineur à l’exemple fr.po précédent. Une page Razor située dans Pages/Index.cshtml peut être définie comme contexte de fichier en définissant la valeur de l’entrée msgctxt réservée :
msgctxt "Views.Home.About"
msgid "Hello world!"
msgstr "Bonjour le monde!"
Avec msgctxt ainsi définie, la traduction de texte se produit lors de la navigation vers /Index?culture=fr-FR. La traduction ne se produit pas lors de la navigation vers /Privacy?culture=fr-FR.
Quand aucune entrée spécifique ne correspond à un contexte de fichier donné, le mécanisme de secours d’Orchard Core recherche un fichier PO approprié sans contexte. En supposant qu’aucun contexte de fichier spécifique n’est défini pour Pages/Privacy.cshtml, la navigation vers /Privacy?culture=fr-FR charge un fichier PO tel que le suivant :
msgid "Hello world!"
msgstr "Bonjour le monde!"
Changement de l’emplacement des fichiers PO
L’emplacement par défaut des fichiers PO peut être changé dans Programs.cs :
services.AddPortableObjectLocalization(options => options.ResourcesPath = "Localization");
Dans cet exemple, les fichiers PO sont chargés à partir du dossier Localisation.
Implémentation d’une logique personnalisée pour la recherche de fichiers de localisation
Quand une logique plus complexe est nécessaire pour localiser des fichiers PO, l’interface OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider peut être implémentée et inscrite comme service. Cela est utile quand les fichiers PO peuvent être stockés dans différents emplacements ou quand la recherche des fichiers doit être effectuée dans une hiérarchie de dossiers.
Utilisation d’une autre langue pluralisée par défaut
Le package inclut une méthode d’extension Plural spécifique à deux formes plurielles. Pour les langues nécessitant plus de formes plurielles, créez une méthode d’extension. Avec une méthode d’extension, vous n’avez pas à fournir de fichier de localisation pour la langue par défaut : en effet, les chaînes d’origine sont déjà disponibles directement dans le code.
Vous pouvez utiliser la surcharge Plural(int count, string[] pluralForms, params object[] arguments) plus générique qui accepte un tableau de chaînes des traductions.
Par Sébastien Ros, Scott Addie et Hisham Bin Ateya
Cet article présente les étapes d’utilisation d’objets portables (PO, Portable Object) dans une application ASP.NET Core avec le framework Orchard Core.
Remarque : Orchard Core n’est pas un produit Microsoft. Par conséquent, Microsoft ne fournit aucun support pour cette fonctionnalité.
Affichez ou téléchargez l’exemple de code (procédure de téléchargement)
Qu’est-ce qu’un fichier PO ?
Les fichiers PO sont distribués sous forme de fichiers texte contenant les chaînes traduites pour une langue donnée. L’utilisation de fichiers PO plutôt que des fichiers .resx présente certains avantages, notamment les suivants :
- Les fichiers PO prennent en charge la pluralisation, contrairement aux fichiers .resx.
- Les fichiers PO ne sont pas compilés comme les fichiers .resx. De ce fait, il n’est pas nécessaire d’effectuer les étapes relatives aux outils et à la génération.
- Les fichiers PO fonctionnent correctement avec les outils d’édition collaboratifs en ligne.
Exemple
Voici un exemple de fichier PO contenant la traduction de deux chaînes en français, dont une avec sa forme au pluriel :
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."
Cet exemple utilise la syntaxe suivante :
#:: commentaire indiquant le contexte de la chaîne à traduire. La même chaîne peut être traduite différemment selon l’endroit où elle est utilisée.msgid: la chaîne non traduite.msgstr: la chaîne traduite.
Dans le cas de la prise en charge de la pluralisation, des entrées supplémentaires peuvent être définies.
msgid_plural: la chaîne au pluriel non traduite.msgstr[0]: la chaîne traduite pour le cas 0.msgstr[N]: la chaîne traduite pour le cas N.
La spécification du fichier PO se trouve ici.
Configuration de la prise en charge du fichier PO dans ASP.NET Core
Cet exemple est basé sur une application ASP.NET Core MVC générée à partir d’un modèle de projet Visual Studio 2019.
Référencement du package
Ajoutez une référence au package NuGet OrchardCore.Localization.Core.
Le fichier .csproj contient maintenant une ligne semblable à la suivante (le numéro de version peut varier) :
<PackageReference Include="OrchardCore.Localization.Core" Version="1.2.0" />
Inscription du service
Ajoutez les services nécessaires à la méthode ConfigureServices de 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")
);
}
Ajoutez l’intergiciel nécessaire à la méthode Configure de 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?}");
});
}
Ajoutez le code suivant à la page Razor de votre choix. Index.cshtml est utilisé dans cet exemple.
@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>
Une instance IViewLocalizer est injectée et utilisée pour traduire le texte « Hello world! ».
Création d’un fichier PO
Créez un fichier nommé <code de culture>.po dans le dossier racine de votre application. Dans cet exemple, le nom de fichier est fr.po, car le français est utilisé :
msgid "Hello world!"
msgstr "Bonjour le monde!"
Ce fichier stocke à la fois la chaîne à traduire et la chaîne traduite en français. La culture parente des traductions peut être rétablie, si nécessaire. Dans cet exemple, le fichier fr.po est utilisé si la culture demandée est fr-FR ou fr-CA.
Test de l’application
Exécutez votre application, puis accédez à l’URL /Index. Le texte Hello world! s’affiche.
Accédez à l’URL /Index?culture=fr-FR. Le texte Bonjour le monde ! s’affiche.
Forme plurielle
Les fichiers PO prennent en charge les formes de pluralisation, ce qui est utile quand la même chaîne doit être traduite différemment en fonction d’une cardinalité. Cette tâche est rendue compliquée par le fait que chaque langue définit des règles personnalisées pour sélectionner la chaîne à utiliser en fonction de la cardinalité.
Le package de localisation Orchard fournit une API pour appeler automatiquement ces différentes formes plurielles.
Création de fichiers PO de pluralisation
Ajoutez le contenu suivant au fichier fr.po mentionné précédemment :
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."
Consultez Qu’est-ce qu’un fichier PO ? pour obtenir une explication de ce que représente chaque entrée de cet exemple.
Ajout d’une langue utilisant différentes formes de pluralisation
Des chaînes en anglais et en français ont été utilisées dans l’exemple précédent. L’anglais et le français n’ont que deux formes de pluralisation et partagent les mêmes règles de forme, qui est qu’une cardinalité de 1 est mappée à la première forme plurielle. N’importe quelle autre cardinalité est mappée à la seconde forme plurielle.
Toutes les langues ne partagent pas les mêmes règles. À titre d’exemple, il y a la langue tchèque qui a trois formes plurielles.
Créez le fichier cs.po comme suit, puis notez comment la pluralisation a besoin de trois traductions différentes :
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."
Pour accepter les localisations tchèques, ajoutez "cs" à la liste des cultures prises en charge dans la méthode ConfigureServices :
services.Configure<RequestLocalizationOptions>(options => options
.AddSupportedCultures("fr", "cs")
.AddSupportedUICultures("fr", "cs")
);
Modifiez le fichier Pages/Index.cshtml pour restituer des chaînes localisées au pluriel pour plusieurs cardinalités :
<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>
Remarque : Dans un scénario réel, une variable serait utilisée pour représenter le nombre. Ici, nous répétons le même code avec trois valeurs différentes pour exposer un cas très spécifique.
Quand vous passez d’une culture à l’autre, vous voyez ceci :
Pour /Index:
There is one item.
There are 2 items.
There are 5 items.
Pour /Index?culture=fr:
Il y a un élément.
Il y a 2 éléments.
Il y a 5 éléments.
Pour /Index?culture=cs:
Existuje jedna položka.
Existují 2 položky.
Existuje 5 položek.
Notez que pour la culture tchèque, les trois traductions sont différentes. Les cultures anglaise et française partagent la même construction pour les deux dernières chaînes traduites.
Tâches avancées
Contextualisation de chaînes
Les applications contiennent souvent les chaînes à traduire dans plusieurs emplacements. La même chaîne peut avoir une traduction différente dans certains emplacements d’une application (vues Razor ou fichiers de classe). Un fichier PO prend en charge la notion d’un contexte de fichier, qui peut être utilisé pour catégoriser la chaîne représentée. L’utilisation d’un contexte de fichier permet de traduire une chaîne différemment en fonction du contexte du fichier (ou de l’absence de contexte de fichier).
Les services de localisation de PO utilisent le nom de la classe complète ou de la vue utilisée lors de la traduction d’une chaîne. Pour ce faire, il vous suffit de définir la valeur sur l’entrée msgctxt.
Examinons un ajout mineur à l’exemple fr.po précédent. Une vue Razor située dans Pages/Index.cshtml peut être définie comme contexte de fichier en définissant la valeur de l’entrée msgctxt réservée :
msgctxt "Pages.Index"
msgid "Hello world!"
msgstr "Bonjour le monde!"
Avec msgctxt ainsi définie, la traduction de texte se produit lors de la navigation vers /Index?culture=fr-FR. La traduction ne se produit pas lors de la navigation vers /Privacy?culture=fr-FR.
Quand aucune entrée spécifique ne correspond à un contexte de fichier donné, le mécanisme de secours d’Orchard Core recherche un fichier PO approprié sans contexte. En supposant qu’aucun contexte de fichier spécifique n’est défini pour Pages/Privacy.cshtml, la navigation vers /Privacy?culture=fr-FR charge un fichier PO tel que le suivant :
msgid "Hello world!"
msgstr "Bonjour le monde!"
Changement de l’emplacement des fichiers PO
L’emplacement par défaut des fichiers PO peut être changé dans ConfigureServices :
services.AddPortableObjectLocalization(options => options.ResourcesPath = "Localization");
Dans cet exemple, les fichiers PO sont chargés à partir du dossier Localisation.
Implémentation d’une logique personnalisée pour la recherche de fichiers de localisation
Quand une logique plus complexe est nécessaire pour localiser des fichiers PO, l’interface OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider peut être implémentée et inscrite comme service. Cela est utile quand les fichiers PO peuvent être stockés dans différents emplacements ou quand la recherche des fichiers doit être effectuée dans une hiérarchie de dossiers.
Utilisation d’une autre langue pluralisée par défaut
Le package inclut une méthode d’extension Plural spécifique à deux formes plurielles. Pour les langues nécessitant plus de formes plurielles, créez une méthode d’extension. Avec une méthode d’extension, vous n’avez pas à fournir de fichier de localisation pour la langue par défaut : en effet, les chaînes d’origine sont déjà disponibles directement dans le code.
Vous pouvez utiliser la surcharge Plural(int count, string[] pluralForms, params object[] arguments) plus générique qui accepte un tableau de chaînes des traductions.
Par Sébastien Ros, Scott Addie et Hisham Bin Ateya
Cet article présente les étapes d’utilisation d’objets portables (PO, Portable Object) dans une application ASP.NET Core avec le framework Orchard Core.
Remarque : Orchard Core n’est pas un produit Microsoft. Par conséquent, Microsoft ne fournit aucun support pour cette fonctionnalité.
Affichez ou téléchargez l’exemple de code (procédure de téléchargement)
Qu’est-ce qu’un fichier PO ?
Les fichiers PO sont distribués sous forme de fichiers texte contenant les chaînes traduites pour une langue donnée. L’utilisation de fichiers PO plutôt que des fichiers .resx présente certains avantages, notamment les suivants :
- Les fichiers PO prennent en charge la pluralisation, contrairement aux fichiers .resx.
- Les fichiers PO ne sont pas compilés comme les fichiers .resx. De ce fait, il n’est pas nécessaire d’effectuer les étapes relatives aux outils et à la génération.
- Les fichiers PO fonctionnent correctement avec les outils d’édition collaboratifs en ligne.
Exemple
Voici un exemple de fichier PO contenant la traduction de deux chaînes en français, dont une avec sa forme au pluriel :
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}\""
Cet exemple utilise la syntaxe suivante :
#:: commentaire indiquant le contexte de la chaîne à traduire. La même chaîne peut être traduite différemment selon l’endroit où elle est utilisée.msgid: la chaîne non traduite.msgstr: la chaîne traduite.
Dans le cas de la prise en charge de la pluralisation, des entrées supplémentaires peuvent être définies.
msgid_plural: la chaîne au pluriel non traduite.msgstr[0]: la chaîne traduite pour le cas 0.msgstr[N]: la chaîne traduite pour le cas N.
La spécification du fichier PO se trouve ici.
Configuration de la prise en charge du fichier PO dans ASP.NET Core
Cet exemple est basé sur une application ASP.NET Core MVC générée à partir d’un modèle de projet Visual Studio 2017.
Référencement du package
Ajoutez une référence au package NuGet OrchardCore.Localization.Core.
Le fichier .csproj contient maintenant une ligne semblable à la suivante (le numéro de version peut varier) :
<PackageReference Include="OrchardCore.Localization.Core" Version="1.0.0" />
Inscription du service
Ajoutez les services nécessaires à la méthode ConfigureServices de 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;
});
}
Ajoutez l’intergiciel nécessaire à la méthode Configure de 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?}");
});
}
Ajoutez le code suivant à la vue Razor de votre choix. About.cshtml est utilisé dans cet exemple.
@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer
<p>@Localizer["Hello world!"]</p>
Une instance IViewLocalizer est injectée et utilisée pour traduire le texte « Hello world! ».
Création d’un fichier PO
Créez un fichier nommé <code de culture>.po dans le dossier racine de votre application. Dans cet exemple, le nom de fichier est fr.po, car le français est utilisé :
msgid "Hello world!"
msgstr "Bonjour le monde!"
Ce fichier stocke à la fois la chaîne à traduire et la chaîne traduite en français. La culture parente des traductions peut être rétablie, si nécessaire. Dans cet exemple, le fichier fr.po est utilisé si la culture demandée est fr-FR ou fr-CA.
Test de l’application
Exécutez votre application, puis accédez à l’URL /Home/About. Le texte Hello world! s’affiche.
Accédez à l’URL /Home/About?culture=fr-FR. Le texte Bonjour le monde ! s’affiche.
Forme plurielle
Les fichiers PO prennent en charge les formes de pluralisation, ce qui est utile quand la même chaîne doit être traduite différemment en fonction d’une cardinalité. Cette tâche est rendue compliquée par le fait que chaque langue définit des règles personnalisées pour sélectionner la chaîne à utiliser en fonction de la cardinalité.
Le package de localisation Orchard fournit une API pour appeler automatiquement ces différentes formes plurielles.
Création de fichiers PO de pluralisation
Ajoutez le contenu suivant au fichier fr.po mentionné précédemment :
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."
Consultez Qu’est-ce qu’un fichier PO ? pour obtenir une explication de ce que représente chaque entrée de cet exemple.
Ajout d’une langue utilisant différentes formes de pluralisation
Des chaînes en anglais et en français ont été utilisées dans l’exemple précédent. L’anglais et le français n’ont que deux formes de pluralisation et partagent les mêmes règles de forme, qui est qu’une cardinalité de 1 est mappée à la première forme plurielle. N’importe quelle autre cardinalité est mappée à la seconde forme plurielle.
Toutes les langues ne partagent pas les mêmes règles. À titre d’exemple, il y a la langue tchèque qui a trois formes plurielles.
Créez le fichier cs.po comme suit, puis notez comment la pluralisation a besoin de trois traductions différentes :
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."
Pour accepter les localisations tchèques, ajoutez "cs" à la liste des cultures prises en charge dans la méthode ConfigureServices :
var supportedCultures = new List<CultureInfo>
{
new CultureInfo("en-US"),
new CultureInfo("en"),
new CultureInfo("fr-FR"),
new CultureInfo("fr"),
new CultureInfo("cs")
};
Modifiez le fichier Views/Home/About.cshtml pour restituer des chaînes localisées au pluriel pour plusieurs cardinalités :
<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>
Remarque : Dans un scénario réel, une variable serait utilisée pour représenter le nombre. Ici, nous répétons le même code avec trois valeurs différentes pour exposer un cas très spécifique.
Quand vous passez d’une culture à l’autre, vous voyez ceci :
Pour /Home/About:
There is one item.
There are 2 items.
There are 5 items.
Pour /Home/About?culture=fr:
Il y a un élément.
Il y a 2 éléments.
Il y a 5 éléments.
Pour /Home/About?culture=cs:
Existuje jedna položka.
Existují 2 položky.
Existuje 5 položek.
Notez que pour la culture tchèque, les trois traductions sont différentes. Les cultures anglaise et française partagent la même construction pour les deux dernières chaînes traduites.
Tâches avancées
Contextualisation de chaînes
Les applications contiennent souvent les chaînes à traduire dans plusieurs emplacements. La même chaîne peut avoir une traduction différente dans certains emplacements d’une application (vues Razor ou fichiers de classe). Un fichier PO prend en charge la notion d’un contexte de fichier, qui peut être utilisé pour catégoriser la chaîne représentée. L’utilisation d’un contexte de fichier permet de traduire une chaîne différemment en fonction du contexte du fichier (ou de l’absence de contexte de fichier).
Les services de localisation de PO utilisent le nom de la classe complète ou de la vue utilisée lors de la traduction d’une chaîne. Pour ce faire, il vous suffit de définir la valeur sur l’entrée msgctxt.
Examinons un ajout mineur à l’exemple fr.po précédent. Une vue Razor située dans Views/Home/About.cshtml peut être définie comme contexte de fichier en définissant la valeur de l’entrée msgctxt réservée :
msgctxt "Views.Home.About"
msgid "Hello world!"
msgstr "Bonjour le monde!"
Avec msgctxt ainsi définie, la traduction de texte se produit lors de la navigation vers /Home/About?culture=fr-FR. La traduction ne se produit pas lors de la navigation vers /Home/Contact?culture=fr-FR.
Quand aucune entrée spécifique ne correspond à un contexte de fichier donné, le mécanisme de secours d’Orchard Core recherche un fichier PO approprié sans contexte. En supposant qu’aucun contexte de fichier spécifique n’est défini pour Views/Home/Contact.cshtml, la navigation vers /Home/Contact?culture=fr-FR charge un fichier PO tel que le suivant :
msgid "Hello world!"
msgstr "Bonjour le monde!"
Changement de l’emplacement des fichiers PO
L’emplacement par défaut des fichiers PO peut être changé dans ConfigureServices :
services.AddPortableObjectLocalization(options => options.ResourcesPath = "Localization");
Dans cet exemple, les fichiers PO sont chargés à partir du dossier Localisation.
Implémentation d’une logique personnalisée pour la recherche de fichiers de localisation
Quand une logique plus complexe est nécessaire pour localiser des fichiers PO, l’interface OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider peut être implémentée et inscrite comme service. Cela est utile quand les fichiers PO peuvent être stockés dans différents emplacements ou quand la recherche des fichiers doit être effectuée dans une hiérarchie de dossiers.
Utilisation d’une autre langue pluralisée par défaut
Le package inclut une méthode d’extension Plural spécifique à deux formes plurielles. Pour les langues nécessitant plus de formes plurielles, créez une méthode d’extension. Avec une méthode d’extension, vous n’avez pas à fournir de fichier de localisation pour la langue par défaut : en effet, les chaînes d’origine sont déjà disponibles directement dans le code.
Vous pouvez utiliser la surcharge Plural(int count, string[] pluralForms, params object[] arguments) plus générique qui accepte un tableau de chaînes des traductions.
