Localização do AegiNext
Localize o checkout atual do AegiNext e leia primeiro o código do consumidor real e o código relacionado. Resolva os caminhos do repositório em relação a esse checkout; não incorpore caminhos de máquina do desenvolvedor. O ponto de entrada compartilhado é src/AegiNext.Desktop/I18n/, com namespace AegiNext.Desktop.I18n. Estenda este sistema existente para novos textos de interface.
Escolha o contexto para a alteração
| Alteração | Leia primeiro |
|---|---|
| Texto, pacotes de idioma, entradas faltando ou correspondência de idioma | I18n/Languages/*.json, I18n/Localization.cs, I18n/LocalizationCatalog.cs, I18n/LanguagePackReader.cs |
| Rótulos estáticos, dicas de ferramentas ou nomes de acessibilidade | AXAML consumidor, I18n/LocExtension.cs, I18n/XamlNamespace.cs, Controls/Common/IconText.cs |
| Estado dinâmico, menus, Dock ou títulos de janela | ViewModel/controlador proprietário, Workspace/WorkbenchSession.cs, Windowing/WorkbenchWindowRegistry.cs |
| Primeira exibição, escolhas de idioma ou preferências | App.axaml.cs, Views/MainWindow.axaml.cs, Workspace/WorkbenchStartupPreferences.cs, Settings/Appearance/AppearanceSettingsViewModel.cs |
| Construir ou publicar recursos | AegiNext.Desktop.csproj, scripts/publish/AegiNext.Publish.psm1, docs/en/publishing.md |
Caminhos de produção sem um prefixo completo estão sob src/AegiNext.Desktop/; scripts e documentação são resolvidos a partir da raiz do checkout. Veja docs/en/composable-workspace.md para localização do workspace. Leia references/verification.md quando a verificação for necessária; edições de texto comuns não exigem carregar toda a implementação.
Pacotes de idioma e chaves
Edite os pacotes fonte em I18n/Languages/, não a saída copiada. Mantenha os conjuntos de chaves dos pacotes internos en-US.json e zh-CN.json iguais e adicione ambas as traduções para novas chaves. Pacotes de terceiros podem omitir entradas e usar fallback. Preserve os prefixos proprietários como Workbench, Settings, Preview, Layout, Log, WorkflowLog e WindowChromeProbe. Mantenha chaves semanticamente distintas, como Workbench.Export e Settings.Export.
{
"LanguageName": "English",
"LanguageID": "en-US",
"Strings": {
"Workbench.Cancel": "Cancel"
}
}
Isso ilustra o esquema, não um pacote interno de substituição. Salve como UTF-8 sem BOM. LanguageName deve ser não vazio, LanguageID um identificador de cultura válido, e toda chave não vazia de Strings deve mapear para uma string. system é reservado como um valor de seleção. Rejeite campos raiz duplicados e chaves de texto duplicadas. IDs de idioma são normalizados e comparados sem distinção entre maiúsculas e minúsculas; chaves de texto diferenciam maiúsculas de minúsculas. Preserve índices de argumentos posicionais e semântica de formatação nas traduções.
A inicialização escaneia apenas arquivos *.json de primeiro nível e usa seus IDs internos. Pacotes opcionais malformados produzem diagnósticos de arquivo e são excluídos; todo pacote em um grupo de ID duplicado é excluído. A inicialização falha sem um pacote en-US único e válido. Não oculte falhas de recursos com tabelas de texto C# duplicadas. Alterações de recurso exigem reinicialização; este sistema não possui recarga a quente.
Conteúdo de legenda, nomes de predefinições do usuário, caminhos, sintaxe de script, IDs serializados e identidades de codificador mantêm seu significado de negócio. Mapeamentos de enum para chave pertencem ao recurso, por exemplo Editing/AnimationPropertyLocalization.cs, em vez de expandir o serviço geral.
Contratos de serviço e preferência
- Chame
Initialize(directory)uma vez na thread da UI antes de carregar o AXAML, usandoPath.Combine(AppContext.BaseDirectory, "i18n"). Ele captura a cultura de sistema original da UI; não inicialize por controle/janela. Get(key)lê snapshots imutáveis de qualquer thread: idioma atual, depoisen-US, depois a chave crua. Os resultados não dependem doCurrentUICulturedo chamador; callbacks de reprodução assíncrona usam o mesmo serviço.Format(key, params object[] arguments)usaCurrentCulturepara formatação numérica. Alterações de idioma atualizam a cultura da UI sem alterar a cultura numérica de entrada estabelecida.SetLanguage(lang)executa na thread da UI e aceita IDs instalados ousystem. IDs desconhecidos lançam exceção sem alterar o idioma; seleção/estado efetivo inalterado não notifica novamente.SelectedLanguageIDé a seleção solicitada;CurrentLanguageIDé o pacote resolvido. A correspondência do sistema usa a cultura inicialmente capturada: ID exato, pais, candidatos do mesmo idioma, depois inglês. Chinês/Inglês preferemzh-CN/en-US; outros candidatos são ordenados por ID.KnownLanguagesfornece rótulosLanguageNamee seleçãoLanguageID, além de uma opção de sistema localizada. Não restaure índices fixos de Inglês/Chinês ou uma lista de permissões de preferência.- O serviço não persiste preferências. Aplique a mesma preferência de idioma carregada na inicialização antes do AXAML da MainWindow, e passe esse armazenamento/snapshot para a sessão. Se um pacote salvo estiver temporariamente indisponível, exiba Inglês enquanto preserva o ID salvo e outras preferências.
- Após um
SetLanguagedireto, salvar uma preferência de tema/volume não relacionada não deve redefinir o idioma. Aplique uma nova seleção apenas quando a preferência de idioma em si mudar.
Use Loc para texto estático
O namespace XML padrão do Avalonia registra LocExtension através de XmlnsDefinition, então use {Loc Key=...} sem um prefixo:
<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 precisa de xmlns:common="using:AegiNext.Desktop.Controls.Common". Reutilize a tipografia e dimensionamento do IconText; IconKey identifica o ícone independentemente das chaves/valores traduzidos. Migre Text, Content, Header, dicas de ferramentas e nomes de acessibilidade conforme apropriado; preserve bindings de negócio para conteúdo dinâmico.
Loc retorna uma binding observável, fornece texto imediatamente na assinatura e atualiza nas mudanças de idioma. Preserve o DataContext. Não capture controles alvo, vasculhe árvores, reintroduza Tags de tradução ou substitua bindings ativas por atribuições únicas de Get.
Texto dinâmico e tempo de vida da assinatura
Os estados de play/pause, mudo, gravação de atalho e exportação permanecem vinculados aos seus próprios ViewModels, que chamam Get/Format. Armazene chaves semânticas, enums e argumentos de formato em vez de apenas a última string traduzida. Reutilize manipuladores centralizados de LanguageChanged em sessões, layouts, registros e configurações; evite assinaturas duplicadas.
Para controles programáticos, retenha e libere o handle da binding observável:
var binding = button.Bind(
ContentControl.ContentProperty,
Localization.Observe("Workbench.Cancel").ToBinding());
Observe é atualmente interno ao Desktop. Libere handles/eventos em Closed/Dispose e descarte primeiro uma binding de estado substituída. Providers capturam apenas valores de negócio necessários, como em Views/TrackStyleChangeDialog.cs. Distinga a desconexão temporária de painel fixo da disposição final para que a reconexão ainda receba atualizações.
A atualização de idioma altera apenas a apresentação: sem commits de negócio, recriação de projeto, Undo ou rascunhos descartados. Atualize listas de escolha preservando IDs estáveis, seleção real e entrada bruta inválida; ignore a seleção automática do framework como uma edição do usuário. Reutilize os guards ChoicesRefreshing/ChoicesRefreshed dos Styles/Effects consumidores onde necessário.
Verifique e entregue
Siga os grupos afetados em verification, verificando AXAML compilado, troca ao vivo, estado de negócio e comportamento de release. Inspecione o JSON bruto para completude de chaves; o fallback de Get não pode provar que traduções existem. Alterações de construção/carregamento/publicação exigem diretórios i18n de saída reais, hashes de pacote e inicialização a partir de outro diretório de trabalho. Pacotes macOS usam AegiNext.app/Contents/MacOS/i18n/.
Relate builds/análises reais, testes passados/falhados/pulados, verificações de recursos e aceitação nativa. Reconte chaves/testes a partir de evidências atuais, não totais históricos. Separe resultados do Headless de aparência de botão/ícone, texto longo e menus de plataforma. Preserve escopo e trabalho não relacionado; usar esta skill não autoriza commits ou atualizações de dependência.