Communitygithub.com

raphaelstuart/Aegisub-NEXT

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 live do Avalonia Loc. Use para controles traduzidos, texto dinâmico em view-models, menus, títulos de janela, preferências de idioma e empacotamento de recursos de idioma; conteúdo de legenda, nomes de predefinições do usuário e sintaxe de scripts de efeitos permanecem como dados de negócio.

O que é Aegisub-NEXT?

Esta skill capacita o Claude Code a gerenciar a localização da interface do usuário do projeto AegiNext, um editor de legendas. Ela descreve como adicionar, alterar, revisar e depurar textos traduzidos usando pacotes de idioma JSON, um serviço de localização centralizado e bindings reativas do framework Avalonia. É útil para garantir que todos os textos da interface, como rótulos de botões, menus, títulos de janelas e dicas de ferramentas, sejam exibidos corretamente no idioma selecionado pelo usuário. A skill define contratos precisos para o serviço de localização, orienta sobre como usar a extensão de marcação 'Loc' no XAML para vincular textos, e explica como gerenciar textos dinâmicos em ViewModels. Ela também especifica a estrutura dos pacotes de idioma JSON, as regras para criação e manutenção de chaves de texto, e o processo de verificação para garantir que as alterações funcionem corretamente em diferentes plataformas (Windows, macOS). A skill é essencial para qualquer desenvolvedor que precise contribuir com a internacionalização do AegiNext, fornecendo um guia completo e detalhado sobre o sistema de localização existente.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/raphaelstuart/Aegisub-NEXT/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

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çãoLeia primeiro
Texto, pacotes de idioma, entradas faltando ou correspondência de idiomaI18n/Languages/*.json, I18n/Localization.cs, I18n/LocalizationCatalog.cs, I18n/LanguagePackReader.cs
Rótulos estáticos, dicas de ferramentas ou nomes de acessibilidadeAXAML consumidor, I18n/LocExtension.cs, I18n/XamlNamespace.cs, Controls/Common/IconText.cs
Estado dinâmico, menus, Dock ou títulos de janelaViewModel/controlador proprietário, Workspace/WorkbenchSession.cs, Windowing/WorkbenchWindowRegistry.cs
Primeira exibição, escolhas de idioma ou preferênciasApp.axaml.cs, Views/MainWindow.axaml.cs, Workspace/WorkbenchStartupPreferences.cs, Settings/Appearance/AppearanceSettingsViewModel.cs
Construir ou publicar recursosAegiNext.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, usando Path.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, depois en-US, depois a chave crua. Os resultados não dependem do CurrentUICulture do chamador; callbacks de reprodução assíncrona usam o mesmo serviço.
  • Format(key, params object[] arguments) usa CurrentCulture para 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 ou system. 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 preferem zh-CN/en-US; outros candidatos são ordenados por ID.
  • KnownLanguages fornece rótulos LanguageName e seleção LanguageID, 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 SetLanguage direto, 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.

Habilidades Relacionadas