Communitygithub.com

raphaelstuart/AegiNEXT

Adicionar, alterar, revisar ou depurar a localização da interface do AegiNext usando pacotes de idioma JSON externos, o serviço de Localização compartilhado e as bindings dinâmicas Loc do Avalonia. Use para controles traduzidos, texto dinâmico de view-models, menus, títulos de janelas, preferências de idioma e empacotamento de recursos de idioma; conteúdo de legendas, nomes de presets do usuário e sintaxe de scripts de efeitos permanecem como dados de negócio.

O que é AegiNEXT?

O skill raphaelstuart/AegiNEXT gerencia a localização do editor de legendas AegiNext, permitindo adicionar, modificar, revisar e depurar textos da interface do usuário através de pacotes de idioma JSON externos e do serviço de Localização compartilhado. Ele suporta bindings Avalonia Loc em tempo real para controles estáticos e texto dinâmico, garantindo que menus, títulos de janelas e preferências de idioma sejam atualizados corretamente. O skill é útil para desenvolvedores que precisam internacionalizar o AegiNext ou corrigir problemas de localização, seguindo uma arquitetura que separa claramente dados de negócio (como legendas e scripts) de dados de interface. Funciona nos sistemas Windows, macOS e Linux, interpretando a estrutura de código-fonte e documentação do projeto, para que o desenvolvedor possa realizar alterações localizadas nos arquivos JSON de idioma, bindings XAML e lógica de ViewModel com segurança, sem afetar outras funcionalidades.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

AegiNext Localização

Primeiro, localize o checkout atual do AegiNext, leia o consumidor real e o código relacionado. Os caminhos do repositório são relativos ao diretório raiz do checkout; não escreva caminhos absolutos da máquina de desenvolvimento na implementação. A entrada é src/AegiNext.Desktop/I18n/, namespace é AegiNext.Desktop.I18n. O sistema de localização já está unificado; novos textos devem usar esta entrada.

Escolher contexto por tipo de alteração

AlteraçãoLeitura prioritária
Texto, pacote de idioma, item ausente ou correspondência de idiomaI18n/Languages/*.json, I18n/Localization.cs, I18n/LocalizationCatalog.cs, I18n/LanguagePackReader.cs
Texto de controle estático, dica de ferramenta, nome acessívelAXAML do consumidor, I18n/LocExtension.cs, I18n/XamlNamespace.cs, Controls/Common/IconText.cs
Estado dinâmico, menu, Dock ou título de janelaViewModel/controlador correspondente, Workspace/WorkbenchSession.cs, Windowing/WorkbenchWindowRegistry.cs
Primeira exibição, opções de idioma, preferênciasApp.axaml.cs, Views/MainWindow.axaml.cs, Workspace/WorkbenchStartupPreferences.cs, Settings/Appearance/AppearanceSettingsViewModel.cs
Compilação ou recursos de publicaçãoAegiNext.Desktop.csproj, scripts/publish/AegiNext.Publish.psm1, docs/zh-CN/publishing.md

Os caminhos de código de produção, exceto caminhos completos, estão em src/AegiNext.Desktop/; os scripts e documentos do repositório são resolvidos a partir da raiz do checkout. A convenção completa está na seção de localização de docs/zh-CN/composable-workspace.md. Quando for necessária verificação, leia references/verification.md; não é necessário ler toda a implementação para alterações de texto comuns.

Pacote de idioma e chave

Modifique os arquivos fonte em I18n/Languages/, não trate o diretório de saída como código fonte. Os conjuntos de chaves de en-US.json e zh-CN.json integrados devem ser consistentes; adicione texto para ambos ao incluir uma nova chave. Idiomas de terceiros podem ter itens ausentes e usar fallback. Use os prefixos de origem existentes Workbench, Settings, Preview, Layout, Log, WorkflowLog, WindowChromeProbe; para novos módulos, nomeie de acordo com a responsabilidade real do módulo, mantendo chaves semanticamente diferentes, por exemplo Workbench.Export e Settings.Export.

{
  "LanguageName": "Português (Brasil)",
  "LanguageID": "pt-BR",
  "Strings": {
    "Workbench.Cancel": "Cancelar"
  }
}

Este trecho ilustra a estrutura, não substitui o arquivo integrado completo. Salve como UTF-8 sem BOM. LanguageName não vazio, LanguageID é um identificador de cultura válido, system é um valor de seleção reservado; as chaves de Strings não são vazias e os valores são todos strings. Recuse campos raiz duplicados e chaves de texto duplicadas. A comparação de ID ignora maiúsculas/minúsculas e é normalizada; as chaves de texto diferenciam maiúsculas/minúsculas. Parâmetros posicionais em traduções devem manter o índice e o formato semântico correspondentes.

Na inicialização, apenas arquivos *.json no primeiro nível do diretório de idiomas são escaneados; o ID dentro do arquivo é a referência. Pacotes opcionais corrompidos são registrados no diagnóstico e excluídos; grupos com IDs duplicados conflitantes são totalmente excluídos. Se en-US válido e único estiver ausente, a inicialização falha. Não adicione cópias de texto em C# para mascarar problemas de recursos. As alterações ou adições de recursos entram em vigor após reinicialização; o sistema atual não possui recarga a quente.

Legendas do projeto, nomes de presets do usuário, caminhos de arquivo, palavras-chave e sintaxe de scripts, IDs de serialização e identificadores de codec mantêm o significado de negócio. O mapeamento de enumerações para chaves de texto deve estar no módulo de negócio correspondente, por exemplo Editing/AnimationPropertyLocalization.cs, e não deve expandir o serviço de localização geral.

Contrato de serviço e preferências

  • Initialize(directory) é chamado uma vez na thread da UI, captura a cultura de interface do sistema original; a aplicação inicializa com Path.Combine(AppContext.BaseDirectory, "i18n") antes de carregar o AXAML. Não inicialize repetidamente em cada controle ou janela.
  • Get(key) pode ser lido em threads de segundo plano de um snapshot imutável, na ordem: idioma atual, en-US, chave original. O resultado da tradução não depende do CurrentUICulture da thread chamadora; callbacks de reprodução assíncrona também usam esta entrada.
  • Format(key, params object[] arguments) usa CurrentCulture para formatar valores numéricos. A mudança de idioma sincroniza apenas a cultura da interface; não altera a cultura de entrada de valores numéricos existente devido à tradução.
  • SetLanguage(lang) é chamado apenas na thread da UI, suporta IDs instalados e system. IDs desconhecidos lançam exceção de argumento e mantêm o idioma atual; mudanças para o mesmo valor e estado ativo não são notificadas novamente.
  • SelectedLanguageID é o valor solicitado, CurrentLanguageID é o resultado resolvido; quando system é selecionado, os dois podem ser diferentes. A correspondência de sistema usa a cultura capturada na inicialização, tentando: ID exato, pai, candidato do mesmo idioma; chinês/inglês priorizam zh-CN/en-US, outros candidatos são ordenados por ID, e finalmente fallback para inglês.
  • KnownLanguages exibe LanguageName para a página de configurações, seleciona por LanguageID, e adiciona o texto traduzido "Seguir sistema". Não restaure índices fixos de inglês/china ou lista de permissões de idioma preferido.
  • O serviço não escreve preferências. A página de configurações segue o fluxo de salvamento de preferências existente; a janela principal aplica as mesmas preferências de inicialização já lidas antes de carregar seu próprio AXAML, e passa o mesmo armazenamento/snapshot para a sessão. Quando o pacote de idioma salvo está temporariamente ausente, exibe inglês, mantendo o ID salvo original e outras preferências.
  • Após um SetLanguage direto, salvar preferências não relacionadas (como tema, volume) não deve redefinir o idioma atual; apenas alterações na preferência de idioma em si aplicam a nova seleção.

Uso de Loc para texto estático

O namespace XML padrão do Avalonia já registrou LocExtension via XmlnsDefinition do assembly; use diretamente sem prefixo {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>

O último exemplo requer xmlns:common="using:AegiNext.Desktop.Controls.Common". Reutilize ícones, fontes e altura de linha existentes de IconText; a identidade do ícone é determinada por IconKey, não pode ser inferida da chave de tradução ou do resultado da tradução. Migre Text, Content, Header, dicas de ferramenta e nomes acessíveis de acordo com a propriedade do controle; não sobrescreva texto de estado ou conteúdo dinâmico que ainda precisa de bind de negócio.

Loc retorna uma binding observável, fornecendo o texto atual imediatamente na primeira assinatura e reenviando após mudança de idioma. Mantenha o DataContext de negócio; não capture o controle alvo, escaneie a árvore de controles ou reintroduza Tag para tradução. Não substitua bindings que precisam de atualização imediata por atribuições de Localization.Get de uso único.

Texto dinâmico e ciclo de vida da assinatura

Play/pause, mute, entrada de atalhos, estado de exportação, etc., continuam vinculados ao ViewModel correspondente, cuja lógica de atualização chama Get/Format. O estado salva a chave semântica, enumeração e parâmetros de formato, não apenas a string traduzida da última vez. Sessão, controladores de layout, registradores de janela e janelas de configuração centralizam a atualização de seus textos dinâmicos; reutilize os pontos de entrada existentes de LanguageChanged, evitando assinaturas duplicadas no mesmo objeto.

Controles criados em C# usam a mesma binding observável e mantêm/liberam o handle da binding:

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

Este é um uso interno do assembly Desktop; Observe é atualmente internal. Janelas liberam handles e assinaturas de eventos em Closed/Dispose; substituir bindings de estado libera a binding antiga primeiro. Providers com parâmetros de formato capturam apenas valores de negócio necessários, evitando capturar a janela inteira; veja Views/TrackStyleChangeDialog.cs. Painéis fixos que são temporariamente desanexados e finalmente descartados devem seguir o ciclo de vida existente, não perdendo atualizações de tradução ao serem remontados.

A atualização de idioma altera apenas a apresentação; não deve chamar submissão de negócio, recriar o projeto, avançar Undo ou descartar rascunhos. Ao atualizar a lista de opções de localização, mantenha IDs estáveis, valor selecionado real e texto inválido original; proíba que o feedback de seleção automática do ComboBox seja tratado como edição do usuário. Padrões relacionados estão em Panels/Styles/, Panels/Effects/ com sincronização ChoicesRefreshing/ChoicesRefreshed e proteção de inicialização; reutilize o padrão apenas nos consumidores que precisam.

Verificação e entrega

Execute a referência de verificação de acordo com o escopo da alteração, verificando AXAML compilado real, mudança de idioma, estado de negócio e comportamento de liberação. Verifique a existência de chaves diretamente no JSON; não use o resultado de fallback de Get para provar que a tradução está completa. Ao modificar regras de compilação, carregamento ou publicação, verifique a saída real i18n/, hashes do pacote e inicialização a partir de diretório não padrão. No macOS, o caminho do pacote é AegiNext.app/Contents/MacOS/i18n/.

Relate compilação/análise estática real executada, testes e pulados, recursos de publicação e evidências de aceitação nativa. Números de testes, quantidade de chaves de idioma e falhas existentes devem ser baseados no resultado da execução atual; não fixe o histórico como critério de aceitação. Aceitação visual final de ícones de botão, layout de texto longo e menus de plataforma devem ser relatados separadamente dos resultados Headless. Mantenha o escopo de autorização do usuário, preserve alterações não relacionadas no workspace, e não faça commit automático ou atualização de dependências devido ao uso deste skill.

Habilidades Relacionadas