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ção | Leitura prioritária |
|---|---|
| Texto, pacote de idioma, item ausente ou correspondência de idioma | I18n/Languages/*.json, I18n/Localization.cs, I18n/LocalizationCatalog.cs, I18n/LanguagePackReader.cs |
| Texto de controle estático, dica de ferramenta, nome acessível | AXAML do consumidor, I18n/LocExtension.cs, I18n/XamlNamespace.cs, Controls/Common/IconText.cs |
| Estado dinâmico, menu, Dock ou título de janela | ViewModel/controlador correspondente, Workspace/WorkbenchSession.cs, Windowing/WorkbenchWindowRegistry.cs |
| Primeira exibição, opções de idioma, preferências | App.axaml.cs, Views/MainWindow.axaml.cs, Workspace/WorkbenchStartupPreferences.cs, Settings/Appearance/AppearanceSettingsViewModel.cs |
| Compilação ou recursos de publicação | AegiNext.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 comPath.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 doCurrentUICultureda thread chamadora; callbacks de reprodução assíncrona também usam esta entrada.Format(key, params object[] arguments)usaCurrentCulturepara 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 esystem. 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; quandosystemé 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 priorizamzh-CN/en-US, outros candidatos são ordenados por ID, e finalmente fallback para inglês.KnownLanguagesexibeLanguageNamepara a página de configurações, seleciona porLanguageID, 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
SetLanguagedireto, 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.