AegiNext Lokalisierung
Lokalisieren Sie zuerst das aktuelle AegiNext-Checkout, lesen Sie die tatsächlichen Verbraucher und den zugehörigen Code. Die Repository-Pfade sind relativ zum Checkout-Stammverzeichnis; schreiben Sie keine absoluten Pfade des Entwicklungsrechners in die Implementierung. Der Einstiegspunkt ist src/AegiNext.Desktop/I18n/, der Namespace lautet AegiNext.Desktop.I18n. Das Lokalisierungssystem ist bereits vereinheitlicht; neue Texte folgen diesem Einstiegspunkt.
Kontext nach Änderungstyp auswählen
| Änderung | Priorität lesen |
|---|---|
| Texte, Sprachpakete, fehlende Einträge oder Sprachabgleich | I18n/Languages/*.json, I18n/Localization.cs, I18n/LocalizationCatalog.cs, I18n/LanguagePackReader.cs |
| Statischer Steuerelementtext, Tooltips, Barrierefreiheitsnamen | Verbraucher-AXAML, I18n/LocExtension.cs, I18n/XamlNamespace.cs, Controls/Common/IconText.cs |
| Dynamischer Status, Menüs, Docking oder Fenstertitel | Zugehöriges ViewModel / Controller, Workspace/WorkbenchSession.cs, Windowing/WorkbenchWindowRegistry.cs |
| Erstanzeige, Sprachoptionen, Einstellungen | App.axaml.cs, Views/MainWindow.axaml.cs, Workspace/WorkbenchStartupPreferences.cs, Settings/Appearance/AppearanceSettingsViewModel.cs |
| Build- oder Veröffentlichungsressourcen | AegiNext.Desktop.csproj, scripts/publish/AegiNext.Publish.psm1, docs/zh-CN/publishing.md |
Produktionscodepfade (außer vollständige Pfade) befinden sich unter src/AegiNext.Desktop/; Repository-Skripte und Dokumentation werden vom Checkout-Stammverzeichnis aus aufgelöst. Die vollständigen Konventionen finden Sie im Lokalisierungsabschnitt von docs/zh-CN/composable-workspace.md. Wenn eine Überprüfung erforderlich ist, lesen Sie references/verification.md; lesen Sie nicht alle Implementierungen für gewöhnliche Textänderungen.
Sprachpakete und Schlüssel
Ändern Sie die Quelldatei I18n/Languages/; behandeln Sie das Ausgabeverzeichnis nicht als Quellverzeichnis. Die Schlüsselsätze der integrierten en-US.json und zh-CN.json sind identisch; neue Schlüssel erfordern Text in beiden Sprachen. Drittanbieter-Sprachen können fehlende Einträge haben und auf Fallback zurückgreifen. Übernehmen Sie die bestehenden Quellpräfixe Workbench, Settings, Preview, Layout, Log, WorkflowLog, WindowChromeProbe; neue Module bezeichnen Sie nach ihrer tatsächlichen Verantwortung und behalten Sie semantisch unterschiedliche Schlüssel wie Workbench.Export und Settings.Export bei.
{
"LanguageName": "简体中文",
"LanguageID": "zh-CN",
"Strings": {
"Workbench.Cancel": "取消"
}
}
Dieser Ausschnitt veranschaulicht die Struktur, ersetzt aber nicht die vollständigen integrierten Dateien. Speichern Sie als UTF-8 ohne BOM. LanguageName ist nicht leer, LanguageID ist eine gültige Kultur-ID; system ist ein reservierter Auswahlwert. Die Schlüssel von Strings sind nicht leer, die Werte sind alle Zeichenfolgen. Lehnen Sie doppelte Stammschlüssel und Texts Schlüssel ab. IDs werden case-insensitiv verglichen und normalisiert; Texts Schlüssel sind case-sensitiv. Platzhalter in Übersetzungen müssen den entsprechenden Index und das Formatierungs-Semantik beibehalten.
Beim Start werden nur *.json-Dateien in der obersten Ebene des Sprachverzeichnisses gescannt; die ID innerhalb der Datei ist maßgeblich. Beschädigte optionale Pakete werden protokolliert und ausgeschlossen; doppelte IDs führen zum Ausschluss der gesamten Gruppe. Wenn gültiges und eindeutiges en-US fehlt, schlägt der Start fehl. Fügen Sie keine C#-Kopien von Texten hinzu, um Ressourcenprobleme zu verschleiern. Nach dem Hinzufügen oder Ändern von Ressourcen ist ein Neustart erforderlich; das aktuelle System unterstützt kein Hot Reload.
Projekt-Untertitel, Benutzervoreinstellungsnamen, Dateipfade, Skript-Schlüsselwörter und -Syntax, Serialisierungs-IDs und Encoder-Kennungen behalten ihre fachliche Bedeutung. Die Zuordnung von Enumerationen zu Textschlüsseln erfolgt im entsprechenden Geschäftsmodul, z. B. Editing/AnimationPropertyLocalization.cs, und erweitert nicht den allgemeinen Lokalisierungsdienst.
Dienstvertrag und Einstellungen
Initialize(directory)wird einmalig im UI-Thread aufgerufen und erfasst die ursprüngliche System-UI-Kultur; die Anwendung initialisiert vor dem Laden von AXAML mitPath.Combine(AppContext.BaseDirectory, "i18n"). Nicht in jedem Steuerelement oder Fenster erneut initialisieren.Get(key)kann im Hintergrund-Thread einen unveränderlichen Snapshot lesen; die Reihenfolge ist aktuelle Sprache,en-US, ursprünglicher Schlüssel. Das Übersetzungsergebnis ist nicht abhängig vonCurrentUICulturedes aufrufenden Threads; auch asynchrone Wiedergabe-Callbacks verwenden diesen Einstieg.Format(key, params object[] arguments)formatiert Werte mitCurrentCulture. Sprachwechsel synchronisieren nur die UI-Kultur; die Kultur vorhandener Werteingaben wird nicht durch die Übersetzung geändert.SetLanguage(lang)wechselt nur im UI-Thread und unterstützt installierte IDs sowiesystem. Unbekannte IDs lösen eine Parameterausnahme aus und behalten die aktuelle Sprache; bei gleicher Auswahl und aktivem Status wird keine erneute Benachrichtigung gesendet.SelectedLanguageIDist der angeforderte Wert,CurrentLanguageIDdas aufgelöste Ergebnis; bei Auswahl vonsystemkönnen beide unterschiedlich sein. Die Systemzuordnung verwendet die beim Initialisieren erfasste Kultur und versucht nacheinander exakte ID, übergeordnete Kultur, sprachliche Kandidaten; für Chinesisch/Englisch bevorzugtzh-CN/en-US, andere Kandidaten sortiert nach ID, schließlich Fallback auf Englisch.KnownLanguagesdient der Anzeige im Einstellungsbereich mitLanguageName, Auswahl nachLanguageID, plus übersetztem „System folgen“. Keine festen Indizes für Chinesisch/Englisch oder eine Whitelist für bevorzugte Sprachen wiederherstellen.- Der Dienst speichert keine Einstellungen. Der Einstellungsbereich verwendet den vorhandenen Speichervorgang; das Hauptfenster wendet vor dem Laden seiner eigenen AXAML dieselbe gelesene Starteinstellung an und übergibt denselben Store/Snapshot an die Sitzung. Wenn das gespeicherte Sprachpaket vorübergehend fehlt, wird Englisch angezeigt; die gespeicherte ID und andere Einstellungen bleiben erhalten.
- Nach direktem
SetLanguagedürfen nicht-sprachbezogene Einstellungen wie Thema, Lautstärke usw. die aktuelle Sprache nicht zurücksetzen; nur wenn sich die Spracheinstellung selbst ändert, wird die neue Auswahl angewendet.
Statische Texte mit Loc
Der standardmäßige Avalonia-XML-Namespace ist bereits über die Assembly-XmlnsDefinition für LocExtension registriert; verwenden Sie direkt präfixloses {Loc Key=...}:
<TextBlock Text="{Loc Key=Workbench.Codec}" />
<Button Content="{Loc Key=Workbench.Cancel}" />
<Expander Header="{Loc Key=Settings.Advanced}" />
<Button ToolTip.Tip="{Loc Key=Workbench.Save}">
<common:IconText Text="{Loc Key=Workbench.Save}" IconKey="Save" />
</Button>
Das letzte Beispiel erfordert xmlns:common="using:AegiNext.Desktop.Controls.Common". Verwenden Sie die vorhandenen Symbole, Schriftarten und Zeilenhöhen von IconText; die Symbolidentität wird durch IconKey bestimmt und darf nicht aus dem Übersetzungsschlüssel oder -ergebnis abgeleitet werden. Migrieren Sie Text, Content, Header, Tooltips und Barrierefreiheitsnamen entsprechend den Steuerelementeigenschaften; überschreiben Sie keinen Status Text oder dynamischen Inhalt, der noch eine Geschäftsdatabindung benötigt.
Loc gibt eine beobachtbare Bindung zurück, die beim ersten Abonnieren sofort den aktuellen Text liefert und nach Sprachwechsel aktualisiert. Behalten Sie den Geschäfts-DataContext; erfassen Sie kein Zielsteuerelement, durchsuchen Sie keine Steuerelementbäume und führen Sie kein Tag für Übersetzungen wieder ein. Verwenden Sie keine einmalige Localization.Get-Zuweisung als Ersatz für Bindungen, die aktualisiert werden müssen.
Dynamischer Text und Abonnement-Lebenszyklus
Wiedergabe/Pause, Stummschaltung, Tastenkombinationseingabe, Exportstatus usw. bleiben an das zugehörige ViewModel gebunden; dessen Aktualisierungslogik ruft Get/Format auf. Der Status speichert semantische Schlüssel, Enumerationen und Formatparameter und nicht nur die zuletzt übersetzte Zeichenfolge. Sitzungen, Layout-Controller, Fensterregistrierungen und Einstellungsfenster aktualisieren ihre jeweiligen dynamischen Texte zentral; verwenden Sie zunächst die vorhandenen LanguageChanged-Verarbeitungseinstiegspunkte und vermeiden Sie wiederholte Abonnements für dasselbe Objekt.
Von C# erstellte Steuerelemente verwenden dieselbe beobachtbare Bindung und halten/freigeben Bindungshandles:
var binding = button.Bind(
ContentControl.ContentProperty,
Localization.Observe("Workbench.Cancel").ToBinding());
Dies ist eine interne Verwendung innerhalb der Desktop-Assembly; Observe ist derzeit internal. Fenster geben in Closed/Dispose Handles und Ereignisabonnements frei; ersetzen Sie Statusbindungen, indem Sie zuerst die alte Bindung freigeben. Der Provider mit Formatparametern erfasst nur die erforderlichen Geschäftswerte und vermeidet das Erfassen des gesamten Fensters; siehe Views/TrackStyleChangeDialog.cs. Temporäres Abtrennen und endgültiges Freigeben fester Panels muss gemäß dem vorhandenen Lebenszyklus unterschieden werden; beim erneuten Einhängen darf die Übersetzungsaktualisierung nicht verloren gehen.
Sprachwechsel ändert nur die Darstellung und darf keine Geschäftsvorgänge auslösen, das Projekt neu aufbauen, Undo-Schritte vorantreiben oder Entwürfe verwerfen. Beim Aktualisieren der Lokalisierungsoptionsliste müssen stabile IDs, der tatsächliche Auswahlwert und der ursprüngliche ungültige Text beibehalten werden; die automatische Auswahlrückmeldung eines ComboBox darf nicht als Benutzereingabe behandelt werden. Das entsprechende Muster finden Sie in Panels/Styles/ und Panels/Effects/ mit den synchronen ChoicesRefreshing/ChoicesRefreshed-Ereignissen und Initialisierungsschutz; verwenden Sie dieses Muster nur bei Bedarf in den Verbrauchern.
Überprüfung und Abnahme
Führen Sie je nach Änderungsumfang die Überprüfungsreferenz aus und überprüfen Sie die tatsächlich kompilierte AXAML, den Sprachwechsel, den Geschäftsstatus und das Freigabeverhalten. Die Existenz von Schlüsseln wird direkt in JSON überprüft; das Fallback-Ergebnis von Get reicht nicht als Nachweis für vollständige Übersetzung. Wenn Build-, Lade- oder Veröffentlichungsregeln geändert werden, überprüfen Sie das tatsächliche Ausgabeverzeichnis i18n/, Paket-Hashes und den Start aus einem Nicht-Programm-Arbeitsverzeichnis. Der macOS-Paketpfad lautet AegiNext.app/Contents/MacOS/i18n/.
Berichten Sie über die tatsächlich durchgeführte Kompilierung/statische Analyse, Tests und Überspringungen, Veröffentlichungsressourcen und native Abnahmenachweise. Anzahl der Tests, Anzahl der Sprachschlüssel und bestehende Fehler beziehen sich auf das aktuelle Ausführungsergebnis; historische Aufzeichnungen werden nicht als Abnahmekriterium herangezogen. Trennen Sie die endgültige visuelle Abnahme von Schaltflächensymbolen, Langtext-Layout und Plattformmenüs von Headless-Ergebnissen. Beachten Sie die Benutzerautorisierung, behalten Sie nicht relevante Arbeitsbereichsänderungen bei und führen Sie keine automatischen Commits oder Abhängigkeitsupdates durch, nur weil dieses Skill verwendet wurde.