Localisation

PowerPortalsPro utilise un système de localisation JSON pour tout le texte destiné à l’utilisateur. Cela inclut les étiquettes de composants, les noms de tables et de colonnes, les noms de vues, les messages de validation et les chaînes spécifiques à chaque application. La pile Blazor les IStringLocalizerlit ; la pile Réaction les lit à travers le useT() crochet. Les deux piles consomment la MÊME forme JSON — les chaînes créées une fois dans app.en.json l’univers entraînent les deux piles (et tout fichier de ressources partagé comme les chaînes dérivées tables.* des métadonnées Dataverse circule automatiquement vers les deux).

Fichiers de localisation

La localisation est pilotée par des fichiers JSON placés dans un localization répertoire du projet serveur. Les fichiers suivent la convention name.{culture}.json de nommage (par app.en.jsonexemple , app.fr.json). La même forme JSON pilote à la fois la pile React (récupérée à l’exécution par le fournisseur localisateur) et la pile Blazor (lue au démarrage par IStringLocalizer).

Réagir

Du côté React, le localisateur est monté automatiquement par <PowerPortalsProProvider> — il inclut un <DefaultLocalizerProvider> qui récupère le paquet de la zone active depuis /localizations/... le montage et à chaque changement de localisation. Enveloppez le fournisseur avec un <LocaleProvider> état de changement de localisation explicite (détecté automatiquement par le chemin de l’URL, ASP.NET le cookie de culture, ou navigator.language par défaut). Les chaînes que l’utilisateur voit pendant la brève fenêtre avant que le bundle ne se résolve soient rendues comme leurs clés brutes ; Le fournisseur échange les vraies cordes dès que la récupération atterrit.

Blazor

Enregistrez les répertoires de localisation dans les Program.cs serveurs via AddLocalizationDirectory. Le framework les lit au démarrage, et ils soutiennent tout IStringLocalizer / IStringLocalizer<T> résolu via DI.

Fichiers de localisation HTML

Pour des contenus plus longs comme les modèles d’emails, vous pouvez utiliser des fichiers HTML autonomes au lieu d’intégrer des chaînes HTML en JSON. Le nom du fichier encode le chemin complet de la clé de localisation et la culture, en utilisant le format {key-path}.{culture}.html.

Chaque segment séparé par points du nom du fichier correspond à un niveau de la hiérarchie des clés de localisation. L’avant-dernier segment est le code de culture (par enexemple , fr). Placez ces fichiers dans les mêmes annuaires de localisation enregistrés avec AddLocalizationDirectory.

Par exemple, la structure de fichiers suivante :

Le fichier emails.signup-confirmation.body.en.html correspond à la clé emails.signup-confirmation.body de localisation de la en culture. C’est équivalent à avoir le contenu HTML comme une valeur de chaîne dans votre fichier JSON à ce chemin de clé.

Récupérez le contenu en utilisant la même IStringLocalizer clé correspondant au nom du fichier. Le contenu HTML est retourné sous forme de chaîne localisée et peut être rendu avec ToMarkupString().

Tableaux et étiquettes de colonnes

Les noms d’affichage des tableaux et des colonnes, descriptions et étiquettes de vues sont automatiquement résolus à partir des fichiers de localisation en utilisant la convention tables.{tableName}.label, tables.{tableName}.columns.{columnName}.label, et tables.{tableName}.views.{viewId}.label.

Note

Par défaut, le framework charge les métadonnées de chaque table dans votre environnement Dataverse. Pour tout portail qui prend en charge plusieurs langues, vous devez définir LocalizeAllAvailableTables = false et enregistrer uniquement les tables que vous utilisez réellement — AddTableToLocalize charger chaque table ralentit le réchauffement de démarrage et remplit le cache de chaînes avec des étiquettes que vous n’affichez jamais (un coût payé par langue installée). Enregistrez chaque table dont les labels apparaissent dans l’interface (grilles, formulaires, sous-grilles, graphiques), car une table affichée qui n’est pas localisée affiche ses clés brutes au lieu des labels. account, contact, et adx_externalidentity sont inclus par défaut.

Voir les étiquettes

Les notices de la vue dans le menu déroulant du sélecteur de la vue grille sont localisées sous tables.{tableName}.views.{viewId}.label, où {viewId} est l’GUID de la vue enregistrée Dataverse (sans crochets, minuscules). Cela s’applique à la fois MainGrid aux sélecteurs de vues et SubGrid de vue.

Note

Pour les vues personnalisées définies via CustomViewDefinitions, la même convention s’applique — utiliser le GUID de la vue personnalisée comme clé. Si aucune étiquette localisée n’est trouvée, le nom de la vue provenant des GridViewDefinition métadonnées ou Dataverse est utilisé comme solution de secours.

Affichage des en-têtes de colonne

Les en-têtes de colonnes affichés dans des grilles sont résolus à l’aide d’un motif de secours. Le système cherche d’abord une étiquette de colonne spécifique à la vue en tables.{tableName}.views.{viewId}.columns.{columnName}.label. Si elle n’est pas trouvée, elle revient à l’étiquette de colonne au niveau de la table en tables.{tableName}.columns.{columnName}.label. Les infobulles suivent le même motif en utilisant .description au lieu de .label.

Cela vous permet de remplacer l’en-tête d’une colonne pour une vue spécifique sans affecter son label dans d’autres vues ou éditeurs.

Note

Pour les colonnes provenant d’entités liées (par exemple contact.emailaddress1), le nom de la colonne dans la clé utilise le format avec préfixe alias. Si aucune étiquette spécifique à une vue n’est trouvée, le système construit une étiquette à partir du nom de la colonne liée et de l’étiquette de la colonne parente (par exemple « Email (Primary Contact) »).

Étiquettes de choix (ensemble d’options)

Les inscriptions d’options de colonne de choix sont localisées différemment selon que l’ensemble d’options est à portée de tableau ou global.

Choix à portée de tableau

Les choix à portée de table sont localisés sous tables.{tableName}.choices.{choiceLogicalName}.values.{value}.label. Le nom logique choisi est précédé du nom de la table (par account_accountcategorycodeexemple ).

Choix mondiaux

Les choix globaux (ensembles d’options partagés entre plusieurs tables) sont localisés au niveau racine sous choices.{choiceLogicalName}.values.{value}.label, en dehors de toute section de table.

Note

Les ChoiceEdit composants et MultiSelectChoiceEdit résolvent automatiquement les étiquettes de choix à partir du bon emplacement en fonction de la IsGlobal propriété des métadonnées de la colonne.

Injection du localisateur

Il existe deux façons d’injecter le localisateur de chaînes :

• IStringLocalizer — Accéder à toutes les clés de localisation globalement. Utilisez-le pour les étiquettes de tables, les chaînes partagées, ou lorsque vous avez besoin de la GetPrefixedLocalizer méthode.
• IStringLocalizer<T> — Portée portée à un type de composant spécifique. Les clés sont résolues par rapport au chemin de l’espace de noms du composant dans le fichier JSON (par components.{Namespace}.{ComponentName}.{key}exemple ).

Clés à portée composante

Lors de l’utilisation IStringLocalizer<T>de , les clés sont résolues en fonction de l’espace de noms et du nom de classe du composant. Par exemple, un composant en Pages.Editors.TextEdit.TextEditDemoPage résout des clés issues du components.{AssemblyName}.Pages.Editors.TextEdit.TextEditDemoPage.{key} JSON.

Localisateur préfixé

Utilisez GetPrefixedLocalizer pour créer un sous-localisateur qui prépose automatiquement un préfixe à toutes les recherches clés. Cela est utile pour éviter les préfixes répétitifs dans les composants qui utilisent de nombreuses touches de la même section.

HTML en chaînes localisées

Les chaînes localisées peuvent contenir du balisage HTML. Utilisez la méthode d’extension ToMarkupString() pour les rendre comme MarkupString dans les modèles Razor.

Trouver le meilleur partenaire

Utilisez FindLocalizedString la recherche de la première clé correspondante dans une liste de candidats. C’est utile pour les schémas de secours où vous voulez d’abord essayer une clé spécifique, puis revenir à une plus générale.

Du côté Réact, il useT() retourne la clé brute quand une chaîne manque — t(key) !== key c’est le test « est-ce que cette clé a été résolue ? » sur lequel vous construisez une marche de secours ? Enveloppez le patron dans un assistant quand vous en avez besoin sur plusieurs sites d’appel.

Interpolation d’arguments

Les cordes peuvent inclure des cordes {0}positionnelles , {1}, ... des espaces réservés qui sont remplacés lors de la recherche. Blazor transmet args comme un tableau params à IStringLocalizer; Réaction les fait passer comme second argument à t(). Les spécificateurs de format optionnels à l’intérieur d’un espace réservé ({0:N0}, {1:yyyy-MM-dd}) sont respectés uniquement par le pipeline de String.Format Blazor ; pour React, préformatez avec Intl.NumberFormat / Intl.DateTimeFormat avant de passer la valeur dedans.

Chargement impatient (React)

En cas d’échec de cache, la pile React récupère paresseusement le bundle par ressource propriétaire (un lot débouncé par ~75 ms) et re-affiche le composant consommant lorsque les chaînes atteignent. Pour éliminer le bref flash des clés brutes, déclarez les préfixes dont une page aura besoin en premier lieu via useLocalization([...]), ou attendez le rendu jusqu’à ce qu’ils se résolvent via l’enveloppe de niveau supérieur <LocalizationBoundary> . Voir la page LocalizationBoundary pour le motif complet.