Lokalisierung

PowerPortalsPro verwendet ein JSON-basiertes Lokalisierungssystem für alle benutzerorientierten Texte. Dazu gehören Komponentenlabels, Tabellen- und Spaltennamen, View-Namen, Validierungsnachrichten und anwendungsspezifische Strings. Der Blazor-Stapel liest sie durch; IStringLocalizerder React-Stapel liest sie durch den useT() Haken. Beide Stacks verbrauchen dieselbe JSON-Form – einmal erstellte app.en.json Strings steuern beide Stacks an (und alle gemeinsam genutzten Ressourcendateien wie Dataverse-Metadata-abgeleitete tables.* Strings fließen automatisch zu beiden).

Lokalisierungsdateien

Die Lokalisierung erfolgt durch JSON-Dateien, die in einem localization Verzeichnis im Serverprojekt platziert werden. Dateien folgen der Namenskonvention name.{culture}.json (z. B. app.en.json, app.fr.json). Die gleiche JSON-Form steuert sowohl den React-Stack (der zur Laufzeit vom Localizer-Anbieter abgerufen wird) als auch den Blazor-Stack (beim Start gelesen von IStringLocalizer).

Reagieren

Auf der React-Seite wird der Localizer automatisch von <PowerPortalsProProvider> — er enthält ein, <DefaultLocalizerProvider> der das Bündel des aktiven Ortes von /localizations/... auf der Montage und bei jeder Lokalisierungsänderung abruft. Wickle den Anbieter mit einem <LocaleProvider> Zustand ein, wenn du explizite Standortwechsel möchtest (automatisch erkannt über den URL-Pfad, ASP.NET Kulturcookie oder navigator.language standardmäßig). Zeichenketten, die der Benutzer während des kurzen Fensters vor der Auflösung des Bündels sieht, werden als ihre Rohschlüssel gerendert; Der Anbieter tauscht die echten Zeichenketten sofort ein, sobald der Abruf landet.

Blazor

Registrieren Sie die Lokalisierungsverzeichnisse im Server über Program.cs AddLocalizationDirectory. Das Framework liest sie beim Start und bestätigt jede IStringLocalizer / IStringLocalizer<T> Resolve über DI.

HTML-Lokalisierungsdateien

Für längere Inhalte wie E-Mail-Vorlagen können Sie eigenständige HTML-Dateien verwenden, anstatt HTML-Strings in JSON einzubetten. Der Dateiname kodiert den vollständigen Pfad und die Kultur des Lokalisierungsschlüssels und verwendet dabei das Format {key-path}.{culture}.html.

Jedes punktseparierte Segment des Dateinamens entspricht einer Ebene in der Hierarchie des Lokalisierungsschlüssels. Das vorletzte Segment ist der Kulturcode (z. B. en, fr). Platzieren Sie diese Dateien in denselben Lokalisierungsverzeichnissen, die bei registriert sind AddLocalizationDirectory.

Zum Beispiel die folgende Dateistruktur:

Die Datei emails.signup-confirmation.body.en.html entspricht dem Lokalisierungsschlüssel emails.signup-confirmation.body der Kultur en . Das entspricht dazu, den HTML-Inhalt als String-Wert in deiner JSON-Datei auf diesem Schlüsselpfad zu haben.

Rufen Sie den Inhalt mit demselben IStringLocalizer Schlüssel ab, der dem Dateinamen entspricht. Der HTML-Inhalt wird als lokalisierte Zeichenkette zurückgegeben und kann mit gerendert werden ToMarkupString().

Tabellen- und Spaltenetiketten

Tabellen- und Spaltenanzeigen, Beschreibungen und View-Labels werden automatisch aus den Lokalisierungsdateien mithilfe der Konvention tables.{tableName}.label, tables.{tableName}.columns.{columnName}.label, und tables.{tableName}.views.{viewId}.labelaufgelöst.

Anmerkung

Standardmäßig lädt das Framework Metadaten für jede Tabelle in Ihrer Dataverse-Umgebung. Für jedes Portal, das mehrere Sprachen unterstützt, solltest du nur die Tabellen festlegen LocalizeAllAvailableTables = false und registrieren, über die du tatsächlich nutzt AddTableToLocalize – das Laden jeder Tabelle verlangsamt das Startaufwärmen und füllt den String-Cache mit Labels, die du nie anweist (ein Kostenfaktor pro installierter Sprache). Registrieren Sie jede Tabelle, deren Labels in der Benutzeroberfläche erscheinen (Raster, Formulare, Untergitter, Diagramme), da eine angezeigte Tabelle, die nicht lokalisiert ist, ihre Rohschlüssel anstelle von Labels rendert. account, contact, und adx_externalidentity sind standardmäßig enthalten.

Etiketten anzeigen

Ansichtsbeschriftungen im Rasteransichts-Dropdown-Menü sind unter tables.{tableName}.views.{viewId}.labellokalisiert, wobei {viewId} die GUID der gespeicherten Ansicht von Dataverse ist (ohne Strebe, Kleinbuchstaben). Dies gilt sowohl für die MainGrid Ansichts- als auch SubGrid für Ansichtsselektoren.

Anmerkung

Für benutzerdefinierte Ansichten, die über definiert sind CustomViewDefinitions, gilt dieselbe Konvention – verwenden Sie die GUID der benutzerdefinierten Ansicht als Schlüssel. Wenn kein lokalisiertes Label gefunden wird, wird der Name der Ansicht aus der GridViewDefinition oder Dataverse-Metadaten als Fallback verwendet.

Spaltenüberschriften anzeigen

Spaltenüberschriften, die in Rastern angezeigt werden, werden mittels eines Rückfallmusters aufgelöst. Das System sucht zunächst nach einer ansichtsspezifischen Spaltenbezeichnung bei tables.{tableName}.views.{viewId}.columns.{columnName}.label. Wenn sie nicht gefunden wird, fällt sie auf das Tabellen-Kolumnenlabel bei tables.{tableName}.columns.{columnName}.labelzurück. Tooltips folgen demselben Muster mit .description anstelle von .label.

Dadurch können Sie die Kopfzeile einer Spalte für eine bestimmte Ansicht überschreiben, ohne deren Beschriftung in anderen Ansichten oder Editoren zu beeinflussen.

Anmerkung

Für Spalten aus verknüpften Entitäten (z. B. contact.emailaddress1), verwendet der Spaltenname im Schlüssel das Alias-präfixierte Format. Wenn kein ansichtsspezifisches Label gefunden wird, erstellt das System ein Label aus dem verknüpften Spaltennamen und dessen übergeordnetem Spaltenlabel (z. B. "Email (Primary Contact)").

Auswahl- (Optionsset-)Bezeichnungen

Optionslabels der Auswahlspalte werden je nachdem, ob der Optionssatz tabellenbezogen oder global ist, unterschiedlich lokalisiert.

Tabellenbezogene Auswahl

Tabellenbezogene Optionen werden unter tables.{tableName}.choices.{choiceLogicalName}.values.{value}.labellokalisiert. Der logische Name der Wahl wird mit dem Tabellennamen (z. B. account_accountcategorycode) vorangestellt.

Globale Entscheidungen

Globale Entscheidungen (Optionsmengen, die über mehrere Tabellen geteilt werden) werden auf Wurzelebene unter choices.{choiceLogicalName}.values.{value}.labellokalisiert, außerhalb eines beliebigen Tabellenabschnitts.

Anmerkung

Die ChoiceEdit und-Komponenten MultiSelectChoiceEdit lösen automatisch Wahllabels von der korrekten Position aus basierend auf der IsGlobal Eigenschaft der Spaltenmetadaten auf.

Injizieren des Localizers

Es gibt zwei Möglichkeiten, den Stringlokalisierer einzuschleusen:

• IStringLocalizer — Zugriff auf alle Lokalisierungsschlüssel weltweit. Nutze das für Tabellenlabels, geteilte Strings oder wenn du die Methode GetPrefixedLocalizer brauchst.
• IStringLocalizer<T> — Auf einen bestimmten Bauteiltyp zugeschnitten. Schlüssel werden relativ zum Namensraumpfad der Komponente in der JSON-Datei aufgelöst (z. B. components.{Namespace}.{ComponentName}.{key}).

Komponenten-Scoped Schlüssel

Bei Verwendung IStringLocalizer<T>werden Schlüssel basierend auf dem Namensraum und dem Klassennamen der Komponente aufgelöst. Zum Beispiel löst eine Komponente bei Pages.Editors.TextEdit.TextEditDemoPage Schlüssel aus dem JSON auf components.{AssemblyName}.Pages.Editors.TextEdit.TextEditDemoPage.{key} .

Präfixlokalisierer

Nutze GetPrefixedLocalizer es, um einen Sublokalisierer zu erstellen, der automatisch ein Präfix an alle Schlüsselsuche setzt. Dies ist nützlich, um wiederholende Schlüsselpräfixe in Komponenten zu vermeiden, die viele Schlüssel aus demselben Abschnitt verwenden.

HTML in lokalisierten Zeichenketten

Lokalisierte Zeichenketten können HTML-Markup enthalten. Verwenden Sie die Erweiterungsmethode ToMarkupString() , um sie wie MarkupString in Razor-Vorlagen zu rendern.

Das beste Match finden

Suchen FindLocalizedString Sie den ersten passenden Schlüssel aus einer Liste von Kandidaten nach. Das ist nützlich für Rückfallmuster, bei denen du zuerst eine bestimmte Taste ausprobieren und dann auf eine allgemeinere zurückgreifen möchtest.

Auf der React-Seite useT() gibt er die rohe Taste zurück, wenn ein String fehlt – t(key) !== key ist die "Hat dieser Schlüssel aufgelöst?"-Check, auf dem du einen Fallback-Walk baust. Wickle das Muster in einen Helfer, wenn du es an mehreren Einsatzorten brauchst.

Argumentinterpolation

Strings können positionelle {0}, {1}, ... Platzhalter, die zur Suchzeit ersetzt werden. Blazor übergibt Args als Params-Array an IStringLocalizer; React übergibt sie als zweites Argument zu t(). Optionale Formatspezifikationen innerhalb eines Platzhalters ({0:N0}, {1:yyyy-MM-dd}) werden nur von Blazors String.Format Pipeline anerkannt; für React wird mit Intl.NumberFormat / Intl.DateTimeFormat vor der Weitergabe des Wertes formatiert.

Eifriges Laden (React)

Bei einem Cache-Miss holt der React-Stack faul das besitzende pro-Ressource-Bundle (ein debounced Batch pro ~75 ms) und rendert die verbrauchende Komponente erneut, wenn die Strings landen. Um den kurzen Flash von Rohtasten zu vermeiden, deklarieren Sie die Präfixe, die eine Seite benötigt, im Voraus über useLocalization([...]), oder verschieben Sie das Rendern, bis sie über den höherwertigen <LocalizationBoundary> Wrapper aufgelöst werden. Siehe die Seite LocalizationBoundary für das vollständige Muster.