Localisation d'AegiNext
Localisez d'abord le répertoire de travail actuel d'AegiNext et lisez le code consommateur et le code connexe réel. Résolvez les chemins des dépôts par rapport à ce répertoire ; n'intégrez pas de chemins de machine de développement. Le point d'entrée partagé est src/AegiNext.Desktop/I18n/, avec l'espace de noms AegiNext.Desktop.I18n. Étendez ce système existant pour les nouveaux textes d'interface.
Choisir le contexte pour la modification
| Modification | À lire en premier |
|---|---|
| Texte, packs de langue, entrées manquantes ou correspondance de langue | I18n/Languages/*.json, I18n/Localization.cs, I18n/LocalizationCatalog.cs, I18n/LanguagePackReader.cs |
| Étiquettes statiques, infobulles ou noms d'accessibilité | AXAML consommateur, I18n/LocExtension.cs, I18n/XamlNamespace.cs, Controls/Common/IconText.cs |
| État dynamique, menus, Dock ou titres de fenêtres | ViewModel/contrôleur propriétaire, Workspace/WorkbenchSession.cs, Windowing/WorkbenchWindowRegistry.cs |
| Premier affichage, choix de langue ou préférences | App.axaml.cs, Views/MainWindow.axaml.cs, Workspace/WorkbenchStartupPreferences.cs, Settings/Appearance/AppearanceSettingsViewModel.cs |
| Construction ou publication de ressources | AegiNext.Desktop.csproj, scripts/publish/AegiNext.Publish.psm1, docs/en/publishing.md |
Les chemins de production sans préfixe complet se trouvent sous src/AegiNext.Desktop/ ; les scripts et la documentation sont résolus à partir de la racine du répertoire. Voir docs/en/composable-workspace.md pour la localisation de l'espace de travail. Lisez references/verification.md lorsque la vérification est nécessaire ; les modifications de texte ordinaires ne nécessitent pas de charger toutes les implémentations.
Packs de langue et clés
Modifiez les packs sources dans I18n/Languages/, pas la sortie copiée. Gardez les ensembles de clés intégrés en-US.json et zh-CN.json égaux et ajoutez les deux traductions pour les nouvelles clés. Les packs tiers peuvent omettre des entrées et utiliser le repli. Préservez les préfixes propriétaires tels que Workbench, Settings, Preview, Layout, Log, WorkflowLog et WindowChromeProbe. Conservez des clés sémantiquement distinctes, comme Workbench.Export et Settings.Export.
{
"LanguageName": "English",
"LanguageID": "en-US",
"Strings": {
"Workbench.Cancel": "Cancel"
}
}
Ceci illustre le schéma, pas un pack intégré de remplacement. Enregistrez en UTF-8 sans BOM. LanguageName doit être non vide, LanguageID un identifiant de culture valide, et chaque clé Strings non vide doit correspondre à une chaîne. system est réservé comme valeur de sélection. Rejetez les champs racine et les clés de texte en double. Les identifiants de langue sont normalisés et comparés sans tenir compte de la casse ; les clés de texte sont sensibles à la casse. Préservez les indices d'arguments positionnels et la sémantique de formatage dans les traductions.
L'analyse de démarrage ne concerne que les fichiers *.json de premier niveau et utilise leurs identifiants internes. Les packs optionnels mal formés produisent des diagnostics de fichier et sont exclus ; chaque pack d'un groupe d'identifiants en double est exclu. Le démarrage échoue sans un pack en-US valide et unique. Ne masquez pas les échecs de ressources avec des tables de texte C# en double. Les modifications de ressources nécessitent un redémarrage ; ce système n'a pas de rechargement à chaud.
Le contenu des sous-titres, les noms de préréglages utilisateur, les chemins, la syntaxe des scripts, les identifiants sérialisés et les identités des encodeurs conservent leur signification métier. Les correspondances énumération-à-clé appartiennent à la fonctionnalité, par exemple Editing/AnimationPropertyLocalization.cs, plutôt que d'étendre le service général.
Contrats de service et de préférences
- Appelez
Initialize(directory)une fois sur le thread de l'interface utilisateur avant de charger AXAML, en utilisantPath.Combine(AppContext.BaseDirectory, "i18n"). Il capture la culture d'interface système d'origine ; ne l'initialisez pas par contrôle/fenêtre. Get(key)lit des instantanés immuables depuis n'importe quel thread : langue actuelle, puisen-US, puis la clé brute. Les résultats ne dépendent pas duCurrentUICulturede l'appelant ; les rappels de lecture asynchrones utilisent le même service.Format(key, params object[] arguments)utiliseCurrentCulturepour le formatage numérique. Les changements de langue mettent à jour la culture de l'interface utilisateur sans modifier la culture de saisie numérique établie.SetLanguage(lang)s'exécute sur le thread de l'interface utilisateur et accepte les identifiants installés ousystem. Les identifiants inconnus lèvent une exception sans changer de langue ; la sélection/état effectif inchangé ne déclenche pas de nouvelle notification.SelectedLanguageIDest la sélection demandée ;CurrentLanguageIDest le pack résolu. La correspondance système utilise la culture initialement capturée : identifiant exact, parents, candidats de même langue, puis anglais. Le chinois/l'anglais préfèrentzh-CN/en-US; les autres candidats sont triés par identifiant.KnownLanguagesfournit les étiquettesLanguageNameet la sélectionLanguageID, plus une option système localisée. Ne restaurez pas les index fixes anglais/chinois ou une liste blanche de préférences.- Le service ne persiste pas les préférences. Appliquez la même préférence de langue chargée au démarrage avant le MainWindow AXAML, et transmettez ce magasin/instantané à la session. Si un pack sauvegardé est temporairement indisponible, affichez l'anglais tout en conservant l'identifiant sauvegardé et les autres préférences.
- Après un
SetLanguagedirect, l'enregistrement d'une préférence de thème/volume non liée ne doit pas réinitialiser la langue. Appliquez une nouvelle sélection uniquement lorsque la préférence de langue elle-même change.
Utiliser Loc pour le texte statique
L'espace de noms XML Avalonia par défaut enregistre LocExtension via XmlnsDefinition, donc utilisez {Loc Key=...} sans préfixe :
<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>
Le dernier exemple nécessite xmlns:common="using:AegiNext.Desktop.Controls.Common". Réutilisez la typographie et le dimensionnement d'IconText ; IconKey identifie l'icône indépendamment des clés/valeurs traduites. Migrez Text, Content, Header, les infobulles et les noms d'accessibilité selon le cas ; préservez les liaisons métier pour le contenu dynamique.
Loc retourne une liaison observable, fournit immédiatement le texte lors de l'abonnement et se met à jour lors des changements de langue. Préservez DataContext. Ne capturez pas les contrôles cibles, ne parcourez pas les arborescences, ne réintroduisez pas de Tags de traduction et ne remplacez pas les liaisons actives par des affectations Get uniques.
Texte dynamique et durée de vie des abonnements
Les états de lecture/pause, sourdine, enregistrement de raccourci et exportation restent liés à leurs ViewModels propriétaires, qui appellent Get/Format. Stockez les clés sémantiques, les énumérations et les arguments de format plutôt que seulement la dernière chaîne traduite. Réutilisez les gestionnaires LanguageChanged centralisés dans les sessions, les mises en page, les registres et les paramètres ; évitez les abonnements en double.
Pour les contrôles programmatiques, conservez et libérez le handle de liaison observable :
var binding = button.Bind(
ContentControl.ContentProperty,
Localization.Observe("Workbench.Cancel").ToBinding());
Observe est actuellement interne à Desktop. Libérez les handles/événements sur Closed/Dispose et supprimez d'abord une liaison d'état remplacé. Les fournisseurs ne capturent que les valeurs métier nécessaires, comme dans Views/TrackStyleChangeDialog.cs. Distinguez le détachement temporaire d'un panneau fixe de l'élimination finale afin que le rattachement reçoive toujours les mises à jour.
Le rafraîchissement de la langue modifie uniquement la présentation : pas de validation métier, de recréation de projet, d'Annulation ou de brouillons abandonnés. Rafraîchissez les listes de choix tout en préservant les identifiants stables, la sélection réelle et les entrées brutes invalides ; ignorez la sélection automatique framework en tant qu'édition utilisateur. Réutilisez les gardes ChoicesRefreshing/ChoicesRefreshed des Styles/Effets consommateurs si nécessaire.
Vérifier et livrer
Suivez les groupes affectés dans vérification, en vérifiant AXAML compilé, la commutation en direct, l'état métier et le comportement de publication. Inspectez le JSON brut pour la complétude des clés ; le repli Get ne peut pas prouver l'existence des traductions. Les modifications de construction/chargement/publication nécessitent des répertoires i18n de sortie réels, des hachages de paquets et un démarrage depuis un autre répertoire de travail. Les paquets macOS utilisent AegiNext.app/Contents/MacOS/i18n/.
Rapportez les builds/analyses réels, les tests réussis/échoués/sautés, les vérifications de ressources et l'acceptation native. Comptez à nouveau les clés/tests à partir de preuves actuelles plutôt que de totaux historiques. Séparez les résultats Headless de l'apparence des boutons/icônes, du texte long et des menus de plateforme. Préservez la portée et le travail non lié ; l'utilisation de ce skill n'autorise pas les commits ou les mises à niveau de dépendances.