Localización de AegiNext
Localiza el checkout actual de AegiNext y lee primero el código de consumo y relacionado. Resuelve las rutas del repositorio con respecto a ese checkout; no incrustes rutas de la máquina del desarrollador. El punto de entrada compartido es src/AegiNext.Desktop/I18n/, con el espacio de nombres AegiNext.Desktop.I18n. Extiende este sistema existente para nuevo texto de la interfaz de usuario.
Elegir el contexto para el cambio
| Cambio | Leer primero |
|---|---|
| Texto, paquetes de idioma, entradas faltantes o coincidencia de idioma | I18n/Languages/*.json, I18n/Localization.cs, I18n/LocalizationCatalog.cs, I18n/LanguagePackReader.cs |
| Etiquetas estáticas, tooltips o nombres de accesibilidad | AXAML de consumo, I18n/LocExtension.cs, I18n/XamlNamespace.cs, Controls/Common/IconText.cs |
| Estado dinámico, menús, Dock o títulos de ventanas | ViewModel/controlador propietario, Workspace/WorkbenchSession.cs, Windowing/WorkbenchWindowRegistry.cs |
| Primera visualización, selección de idioma o preferencias | App.axaml.cs, Views/MainWindow.axaml.cs, Workspace/WorkbenchStartupPreferences.cs, Settings/Appearance/AppearanceSettingsViewModel.cs |
| Compilación o publicación de recursos | AegiNext.Desktop.csproj, scripts/publish/AegiNext.Publish.psm1, docs/en/publishing.md |
Las rutas de producción sin un prefijo completo están bajo src/AegiNext.Desktop/; los scripts y la documentación se resuelven desde la raíz del checkout. Consulta docs/en/composable-workspace.md para la localización del espacio de trabajo. Lee references/verification.md cuando se necesite verificación; las ediciones de texto comunes no requieren cargar cada implementación.
Paquetes de idioma y claves
Edita los paquetes fuente en I18n/Languages/, no en la salida copiada. Mantén los conjuntos de claves de los paquetes integrados en-US.json y zh-CN.json iguales y agrega ambas traducciones para las nuevas claves. Los paquetes de terceros pueden omitir entradas y usar el mecanismo de respaldo. Conserva los prefijos propietarios como Workbench, Settings, Preview, Layout, Log, WorkflowLog y WindowChromeProbe. Mantén claves semánticamente distintas, como Workbench.Export y Settings.Export.
{
"LanguageName": "English",
"LanguageID": "en-US",
"Strings": {
"Workbench.Cancel": "Cancel"
}
}
Esto ilustra el esquema, no es un paquete integrado de reemplazo. Guarda en UTF-8 sin BOM. LanguageName debe ser no vacío, LanguageID un identificador de cultura válido, y cada clave no vacía de Strings debe mapear a una cadena. system está reservado como valor de selección. Rechaza campos raíz duplicados y claves de texto duplicadas. Los IDs de idioma se normalizan y comparan sin distinguir mayúsculas/minúsculas; las claves de texto distinguen mayúsculas/minúsculas. Conserva los índices de argumentos posicionales y la semántica de formato en las traducciones.
El inicio escanea solo archivos *.json de primer nivel y usa sus IDs internos. Los paquetes opcionales con formato incorrecto producen diagnósticos de archivo y se excluyen; cada paquete en un grupo con ID duplicado se excluye. El inicio falla sin un paquete en-US único y válido. No ocultes fallos de recursos con tablas de texto C# duplicadas. Los cambios de recursos requieren reinicio; este sistema no tiene recarga en caliente.
El contenido de subtítulos, nombres de preajustes de usuario, rutas, sintaxis de scripts, IDs serializados e identidades de codificadores conservan su significado de negocio. Los mapeos de enumeración a clave pertenecen a la característica, por ejemplo Editing/AnimationPropertyLocalization.cs, en lugar de expandir el servicio general.
Contratos de servicio y preferencias
- Llama a
Initialize(directory)una vez en el hilo de la interfaz de usuario antes de cargar AXAML, usandoPath.Combine(AppContext.BaseDirectory, "i18n"). Captura la cultura de sistema original de la interfaz de usuario; no inicialices por control/ventana. Get(key)lee instantáneas inmutables desde cualquier hilo: idioma actual, luegoen-US, luego la clave original. Los resultados no dependen delCurrentUICulturedel llamante; las devoluciones de llamada de reproducción asíncrona usan el mismo servicio.Format(key, params object[] arguments)usaCurrentCulturepara formato numérico. Los cambios de idioma actualizan la cultura de la interfaz de usuario sin cambiar la cultura de entrada numérica establecida.SetLanguage(lang)se ejecuta en el hilo de la interfaz de usuario y acepta IDs instalados osystem. Los IDs desconocidos lanzan una excepción sin cambiar el idioma; la selección/estado efectivo sin cambios no notifica de nuevo.SelectedLanguageIDes la selección solicitada;CurrentLanguageIDes el paquete resuelto. La coincidencia con el sistema usa la cultura capturada inicialmente: ID exacto, padres, candidatos del mismo idioma, luego inglés. Chino/Inglés prefierenzh-CN/en-US; otros candidatos ordenan por ID.KnownLanguagesproporciona etiquetasLanguageNamey selecciónLanguageID, además de una opción de sistema localizada. No restaures índices fijos de inglés/chino ni una lista blanca de preferencias.- El servicio no persiste preferencias. Aplica la misma preferencia de idioma cargada al inicio antes del AXAML de MainWindow, y pasa ese almacén/instantánea a la sesión. Si un paquete guardado no está disponible temporalmente, muestra inglés mientras conserva el ID guardado y otras preferencias.
- Después de un
SetLanguagedirecto, guardar una preferencia de tema/volumen no relacionada no debe restablecer el idioma. Aplica una nueva selección solo cuando la preferencia de idioma en sí cambia.
Usar Loc para texto estático
El espacio de nombres XML por defecto de Avalonia registra LocExtension a través de XmlnsDefinition, por lo que usa {Loc Key=...} sin prefijo:
<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>
El último ejemplo necesita xmlns:common="using:AegiNext.Desktop.Controls.Common". Reutiliza la tipografía y el tamaño de IconText; IconKey identifica el icono independientemente de las claves/valores traducidos. Migra Text, Content, Header, tooltips y nombres de accesibilidad según corresponda; conserva los enlaces de negocio para contenido dinámico.
Loc devuelve un enlace observable, proporciona texto inmediatamente al suscribirse y se actualiza con los cambios de idioma. Conserva el DataContext. No captures controles objetivo, recorras árboles, reintroduzcas Tags de traducción ni reemplaces enlaces en vivo con asignaciones Get únicas.
Texto dinámico y ciclo de vida de suscripciones
Los estados de reproducción/pausa, silencio, grabación de atajos y exportación permanecen enlazados a sus ViewModel propietarios, que llaman a Get/Format. Almacena claves semánticas, enumeraciones y argumentos de formato en lugar de solo la última cadena traducida. Reutiliza los manejadores centralizados de LanguageChanged en sesiones, diseños, registros y configuraciones; evita suscripciones duplicadas.
Para controles programáticos, retén y libera el manejador del enlace observable:
var binding = button.Bind(
ContentControl.ContentProperty,
Localization.Observe("Workbench.Cancel").ToBinding());
Observe es actualmente interno a Desktop. Libera los manejadores/eventos al cerrar o al disponer y primero desecha un enlace de estado reemplazado. Los proveedores capturan solo los valores de negocio necesarios, como en Views/TrackStyleChangeDialog.cs. Distingue el desacople temporal de un panel fijo de la disposición final para que el reacople aún reciba actualizaciones.
La actualización de idioma solo cambia la presentación: sin confirmaciones de negocio, recreación de proyectos, Deshacer ni borradores descartados. Actualiza las listas de opciones manteniendo IDs estables, selección real y entrada incorrecta no procesada; ignora la selección automática del framework como una edición de usuario. Reutiliza los guardas Consuming Styles/Effects ChoicesRefreshing/ChoicesRefreshed donde sea necesario.
Verificar y entregar
Sigue los grupos afectados en verification, verificando AXAML compilado, cambio en vivo, estado de negocio y comportamiento de publicación. Inspecciona el JSON sin procesar para verificar la integridad de las claves; el respaldo de Get no puede probar que las traducciones existan. Los cambios de compilación/carga/publicación requieren directorios i18n reales de salida, hashes de paquetes e inicio desde otro directorio de trabajo. Los paquetes de macOS usan AegiNext.app/Contents/MacOS/i18n/.
Reporta compilaciones/análisis reales, pruebas pasadas/fallidas/saltadas, verificaciones de recursos y aceptación nativa. Vuelve a contar claves/pruebas a partir de la evidencia actual, no de totales históricos. Separa los resultados de Headless de la apariencia de botones/iconos, texto largo y menús de plataforma. Conserva el alcance y el trabajo no relacionado; usar esta habilidad no autoriza confirmaciones ni actualizaciones de dependencias.