Communitygithub.com

AegiNEXT 本地化

Ajoutez, modifiez, révisez ou déboguez la localisation de l'interface utilisateur d'AegiNext à l'aide de packs de langue JSON externes, du service de localisation partagé et des liaisons Avalonia Loc en direct. Utilisez-le pour les contrôles traduits, le texte dynamique des modèles de vue, les menus, les titres de fenêtre, les préférences de langue et le packaging des ressources linguistiques ; le contenu des sous-titres, les noms de préréglages utilisateur et la syntaxe des scripts d'effets restent des données métier.

Qu'est-ce que AegiNEXT 本地化 ?

Ce skill permet aux agents IA de gérer la localisation d'AegiNext en ajoutant, modifiant ou vérifiant les traductions via des fichiers JSON de packs de langue externes, le service `Localization` partagé et les liaisons `Loc`. Il couvre les textes statiques des contrôles (AXAML), les textes dynamiques des modèles de vue, les menus, les titres de fenêtre, et les préférences de langue, tout en préservant les données métier comme les sous-titres ou les noms de préréglages. Le skill prend en charge les modifications incrémentielles : il guide l'utilisateur vers les fichiers pertinents (packs de langue, extensions de liaison, ViewModels, services) selon le type de changement, et applique des règles strictes sur les clés (cohérence entre en-US et zh-CN, préfixes de module, paramètres positionnels). Il documente les contrats du service `Localization` (initialisation unique, réservation des clés, rafraîchissement sans cycle de vie, aucun changement métier) et l'utilisation des liaisons `Loc` pour les mises à jour réactives. Enfin, il inclut une section de vérification pour valider la compilation, les tests, le packaging et l'acceptation visuelle, sans actions automatiques (commit, upgrade).

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/raphaelstuart/AegiNEXT/tree/HEAD/.agents/skills/aeginext-localization

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait AegiNEXT 本地化 ?

Commencez par localiser le répertoire de travail actuel d'AegiNext, lisez le code consommateur réel et les fichiers associés. Les chemins de dépôt sont relatifs à la racine du répertoire de travail ; n'écrivez pas les chemins absolus de la machine de développement dans l'implémentation. L'entrée est src/AegiNext.Desktop/I18n/, l'espace de noms est AegiNext.Desktop.I18n. Le système de localisation est unifié ; les nouveaux textes doivent suivre cette entrée.

Choisir le contexte en fonction de la modification

ModificationPriorité de lecture
Texte, packs de langue, éléments manquants ou correspondance de langueI18n/Languages/*.json, I18n/Localization.cs, I18n/LocalizationCatalog.cs, I18n/LanguagePackReader.cs
Texte statique des contrôles, info-bulles, noms d'accessibilitéAXAML consommateur, I18n/LocExtension.cs, I18n/XamlNamespace.cs, Controls/Common/IconText.cs
État dynamique, menus, Dock ou titres de fenêtreViewModel/contrôleur associé, Workspace/WorkbenchSession.cs, Windowing/WorkbenchWindowRegistry.cs
Premier affichage, options de langue, préférencesApp.axaml.cs, Views/MainWindow.axaml.cs, Workspace/WorkbenchStartupPreferences.cs, Settings/Appearance/AppearanceSettingsViewModel.cs
Construction ou publication de ressourcesAegiNext.Desktop.csproj, scripts/publish/AegiNext.Publish.psm1, docs/zh-CN/publishing.md

Les chemins de code de production (hors chemins complets) se trouvent sous src/AegiNext.Desktop/ ; les scripts et la documentation du dépôt sont résolus à partir de la racine du répertoire de travail. La convention complète est dans la section localisation de docs/zh-CN/composable-workspace.md. En cas de besoin de vérification, lisez references/verification.md ; il n'est pas nécessaire de lire toutes les implémentations pour les modifications de texte courantes.

Packs de langue et clés

Modifiez les fichiers sources I18n/Languages/, ne traitez pas le répertoire de sortie comme du code source. Les ensembles de clés de en-US.json et zh-CN.json intégrés restent cohérents ; les nouvelles clés doivent fournir les deux textes. Les langues tierces peuvent avoir des éléments manquants et utiliser un repli (fallback). Conservez les préfixes de source existants Workbench, Settings, Preview, Layout, Log, WorkflowLog, WindowChromeProbe ; pour les nouveaux modules, nommez en fonction de la responsabilité réelle, conservez les clés sémantiquement différentes, par exemple Workbench.Export et Settings.Export.

{
  "LanguageName": "简体中文",
  "LanguageID": "zh-CN",
  "Strings": {
    "Workbench.Cancel": "取消"
  }
}

Cet extrait illustre la structure, ne remplace pas les fichiers intégrés complets. Sauvegardez en UTF-8 sans BOM. LanguageName non vide, LanguageID est un identifiant de culture valide, system est une valeur de sélection réservée ; les clés de Strings sont non vides, les valeurs sont toutes des chaînes. Rejetez les champs racine et les clés de texte en double. La comparaison des ID ignore la casse et normalise, les clés de texte sont sensibles à la casse. Les paramètres positionnels dans les traductions doivent conserver l'index correspondant et la sémantique du format.

Au démarrage, seul le premier niveau de fichiers *.json dans le répertoire des langues est scanné, l'ID à l'intérieur du fichier prévaut. Les paquets optionnels corrompus sont enregistrés pour diagnostic et exclus ; tous les groupes d'ID en double sont exclus. Si en-US valide et unique est manquant, le démarrage échoue. N'ajoutez pas de copies de textes en C# pour masquer les problèmes de ressources. Les modifications ou ajouts de ressources prennent effet après redémarrage, le système actuel n'a pas de rechargement à chaud.

Les sous-titres du projet, les noms de préréglages utilisateur, les chemins de fichiers, les mots-clés et la syntaxe des scripts, les ID de sérialisation et les identifiants de codec conservent leur signification métier. Le mappage des énumérations vers les clés de texte se trouve dans le module métier correspondant, par exemple Editing/AnimationPropertyLocalization.cs, n'étendez pas le service de localisation général.

Contrats du service et préférences

  • Initialize(directory) est appelé une fois sur le thread UI, capture la culture UI système d'origine ; l'application initialise avec Path.Combine(AppContext.BaseDirectory, "i18n") avant de charger les AXAML. Ne réinitialisez pas sur chaque contrôle ou fenêtre.
  • Get(key) peut lire un instantané immuable sur un thread d'arrière-plan, dans l'ordre : langue actuelle, en-US, clé originale. Le résultat de la traduction ne dépend pas du CurrentUICulture du thread appelant ; les rappels de lecture asynchrone utilisent également cette entrée.
  • Format(key, params object[] arguments) formate les nombres avec CurrentCulture. Le changement de langue ne synchronise que la culture de l'interface, ne modifie pas la culture des entrées numériques existantes.
  • SetLanguage(lang) ne bascule que sur le thread UI, prend en charge les ID installés et system. Les ID inconnus lèvent une exception de paramètre et conservent la langue actuelle ; les mêmes sélections et états effectifs ne déclenchent pas de notification redondante.
  • SelectedLanguageID est la valeur demandée, CurrentLanguageID est le résultat résolu ; lorsque system est sélectionné, les deux peuvent différer. La correspondance système utilise la culture capturée lors de l'initialisation, en essayant successivement l'ID exact, le parent, les candidats de la même langue, avec priorité pour zh-CN/en-US pour le chinois/anglais, les autres candidats triés par ID, et enfin repli sur l'anglais.
  • KnownLanguages est utilisé par la page de paramètres pour afficher LanguageName, sélectionner par LanguageID, et ajouter "Suivre le système" traduit. Ne restaurez pas d'index fixes pour le chinois/anglais ou de liste blanche de langues préférées.
  • Le service n'écrit pas les préférences. La page de paramètres suit le flux de sauvegarde des préférences existant ; la fenêtre principale applique les mêmes préférences de démarrage lues avant de charger son propre AXAML et transmet le même store/snapshot à la session. Lorsqu'un pack de langue sauvegardé est temporairement manquant, affichez en anglais, conservez l'ID original sauvegardé et les autres préférences.
  • Après un SetLanguage direct, la sauvegarde des préférences non liées (thème, volume, etc.) ne doit pas réinitialiser la langue actuelle ; la nouvelle sélection n'est appliquée que lorsque la préférence linguistique elle-même change.

Utilisation de Loc pour les textes statiques

L'espace de noms XML Avalonia par défaut est déjà enregistré via XmlnsDefinition de l'assembly pour LocExtension, utilisez directement {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 les icônes, polices et hauteurs de ligne existantes d'IconText ; l'identité de l'icône est déterminée par IconKey, ne peut pas être déduite de la clé de traduction ou du résultat de la traduction. Migrez les propriétés Text, Content, Header, les info-bulles et les noms d'accessibilité en fonction des propriétés du contrôle ; n'écrasez pas les textes d'état ou le contenu dynamique qui nécessitent encore une liaison métier.

Loc retourne une liaison observable, fournit le texte actuel dès la première souscription, et repousse après un changement de langue. Conservez le DataContext métier ; ne capturez pas le contrôle cible, ne scannez pas l'arbre de contrôle, ne réintroduisez pas de Tag pour la traduction. N'utilisez pas d'affectation unique Localization.Get pour remplacer les liaisons nécessitant des mises à jour instantanées.

Texte dynamique et cycle de vie des souscriptions

Les états de lecture/pause, muet, saisie de raccourci, exportation, etc., continuent de lier leur ViewModel respectif, dont la logique de rafraîchissement appelle Get/Format. Les états sauvegardent les clés sémantiques, les énumérations et les paramètres de format, ne peuvent pas seulement mettre en cache la chaîne traduite précédente. Les sessions, les contrôleurs de disposition, les enregistreurs de fenêtre et les fenêtres de paramètres centralisent le rafraîchissement de leurs textes dynamiques respectifs ; réutilisez d'abord les points d'entrée LanguageChanged existants pour éviter les souscriptions redondantes sur le même objet.

Les contrôles créés en C# utilisent la même liaison observable et conservent/libèrent le handle de liaison :

var binding = button.Bind(
    ContentControl.ContentProperty,
    Localization.Observe("Workbench.Cancel").ToBinding());

C'est une utilisation interne à l'assembly Desktop, Observe est actuellement interne. Les fenêtres libèrent les handles et les souscriptions d'événements dans Closed/Dispose ; remplacez les liaisons d'état en libérant d'abord l'ancienne liaison. Le fournisseur avec paramètres de format ne capture que les valeurs métier nécessaires, évitez de capturer toute la fenêtre ; référez-vous à Views/TrackStyleChangeDialog.cs. Les panneaux fixes détachés temporairement et la disposition finale doivent être distingués selon le cycle de vie existant, le remontage ne doit pas perdre les mises à jour de traduction.

Le rafraîchissement de la langue ne modifie que l'affichage, ne peut pas appeler de soumission métier, reconstruire le projet, pousser Undo ou jeter des brouillons. Lors du rafraîchissement de la liste des options de localisation, conservez les ID stables, les valeurs sélectionnées réelles et les textes invalides originaux, interdisez de traiter le feedback de sélection automatique de ComboBox comme une édition utilisateur. Les modèles associés se trouvent dans les synchronisations ChoicesRefreshing/ChoicesRefreshed et la protection d'initialisation de Panels/Styles/, Panels/Effects/ ; ne réutilisez ce modèle que dans les consommateurs qui en ont besoin.

Vérification et livraison

Exécutez la référence de vérification en fonction de la portée de la modification, vérifiez les AXAML réellement compilés, le changement de langue, l'état métier et le comportement de libération. L'existence des clés est vérifiée directement dans le JSON, ne peut pas utiliser le résultat de repli (fallback) de Get pour prouver la complétude des traductions. Lors de la modification des règles de construction, de chargement ou de publication, vérifiez la sortie réelle i18n/, les hachages de paquets et le démarrage depuis un répertoire de travail non-programme. Le chemin du paquet macOS est AegiNext.app/Contents/MacOS/i18n/.

Rapportez la compilation/l'analyse statique réelle effectuée, les tests et les sauts, les ressources publiées et les preuves d'acceptation natives. Le nombre de tests, le nombre de clés de langue et les échecs existants sont basés sur les résultats d'exécution actuels, ne fixez pas l'historique comme critère d'acceptation. Les icônes de boutons, la disposition des textes longs et l'acceptation visuelle finale des menus de la plateforme sont expliqués séparément des résultats Headless. Maintenez la portée d'autorisation de l'utilisateur, conservez les modifications de l'espace de travail non liées, ne committez pas automatiquement et ne mettez pas à jour les dépendances en raison de l'utilisation de ce skill.

Skills associés