Communitygithub.com

raphaelstuart/Aegisub-NEXT

使用外部 JSON 语言包、共享本地化服务和 Avalonia Loc 绑定,添加、修改、审查或调试 AegiNext 界面本地化。适用于翻译控件、动态视图模型文本、菜单、窗口标题、语言偏好和语言资源打包;字幕内容、用户预设名称和效果脚本语法仍保留为业务数据。

Aegisub-NEXT 是什么?

该技能专为 AegiNext 的界面本地化设计,允许开发者通过外部 JSON 语言包添加、修改、审查和调试 UI 文本翻译。它基于现有的 `I18n/` 目录和 `AegiNext.Desktop.I18n` 命名空间,支持静态标签(通过 `LocExtension` AXAML 绑定动态响应语言切换)、动态文本(通过 ViewModel 调用 `Get/Format`)以及窗口标题、菜单、语言偏好等完整场景。用户需编辑内置 `en-US.json` 和 `zh-CN.json` 并保持键集一致,第三方包可缺省回退。核心服务 `Localization` 提供线程安全快照、系统文化匹配、`SetLanguage`/`KnownLanguages` 接口,但**不**持久化偏好,且语言变更需重启应用(无热重载)。技能还强制要求验证构建输出、资源完整性和发布行为,并禁止非授权的提交或依赖升级。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/raphaelstuart/Aegisub-NEXT/tree/HEAD/.agents/skills/aeginext-localization

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

AegiNext 本地化

首先找到当前 AegiNext 检出目录并读取实际的消费代码和相关代码。所有仓库路径依据该检出目录解析;不要嵌入开发者机器上的路径。共享入口点是 src/AegiNext.Desktop/I18n/,命名空间为 AegiNext.Desktop.I18n。在此现有系统的基础上扩展新的 UI 文本。

根据变更选择上下文

变更首先阅读
文本、语言包、缺失条目或语言匹配I18n/Languages/*.json、I18n/Localization.cs、I18n/LocalizationCatalog.cs、I18n/LanguagePackReader.cs
静态标签、工具提示或辅助功能名称消费者 AXAML、I18n/LocExtension.cs、I18n/XamlNamespace.cs、Controls/Common/IconText.cs
动态状态、菜单、Dock 或窗口标题所属 ViewModel/控制器、Workspace/WorkbenchSession.cs、Windowing/WorkbenchWindowRegistry.cs
首次显示、语言选择或偏好App.axaml.cs、Views/MainWindow.axaml.cs、Workspace/WorkbenchStartupPreferences.cs、Settings/Appearance/AppearanceSettingsViewModel.cs
构建或发布资源AegiNext.Desktop.csproj、scripts/publish/AegiNext.Publish.psm1、docs/en/publishing.md

没有完整前缀的生产路径位于 src/AegiNext.Desktop/ 下;脚本和文档从检出根目录解析。有关工作区本地化,请参见 docs/en/composable-workspace.md。当需要验证时,请阅读 references/verification.md;普通文本编辑无需加载所有实现。

语言包和键

编辑 I18n/Languages/ 中的源包,而非复制后的输出。保持内置的 en-US.json 和 zh-CN.json 键集相同,并为新键添加两种语言版本的翻译。第三方包可以省略条目并使用回退。保留拥有前缀,例如 Workbench、Settings、Preview、Layout、Log、WorkflowLog 和 WindowChromeProbe。保持语义上不同的键,例如 Workbench.Export 和 Settings.Export。

{
  "LanguageName": "English",
  "LanguageID": "en-US",
  "Strings": {
    "Workbench.Cancel": "Cancel"
  }
}

这展示了模式,并非替代内置包。以 UTF-8 无 BOM 格式保存。LanguageName 必须非空,LanguageID 为有效的区域性标识符,并且每个非空的 Strings 键必须映射到一个字符串。system 保留用作选择值。拒绝重复的根字段和文本键。语言 ID 标准化后不区分大小写比较;文本键区分大小写。保留位置参数索引和翻译中的格式语义。

启动时仅扫描第一级 *.json 文件并使用其内部 ID。格式错误的可选包会产生文件诊断并被排除;重复 ID 组中的所有包均被排除。如果没有有效的唯一 en-US 包,启动将失败。不要使用重复的 C# 文本表来隐藏资源失败。资源更改需要重新启动;该系统没有热重载。

字幕内容、用户预设名称、路径、脚本语法、序列化 ID 和编码器标识保留其业务含义。枚举到键的映射属于特定功能,例如 Editing/AnimationPropertyLocalization.cs,而不是扩展通用服务。

服务和偏好约定

  • 在加载 AXAML 之前,在 UI 线程上调用一次 Initialize(directory),使用 Path.Combine(AppContext.BaseDirectory, "i18n")。它会捕获原始的系统 UI 区域设置;不要为每个控件/窗口进行初始化。
  • Get(key) 从任何线程读取不可变的快照:当前语言,然后是 en-US,最后是原始键。结果不依赖于调用者的 CurrentUICulture;异步播放回调使用相同的服务。
  • Format(key, params object[] arguments) 使用 CurrentCulture 进行数字格式化。语言更改会更新 UI 区域性,而不更改已建立的数字输入区域性。
  • SetLanguage(lang) 在 UI 线程上运行,并接受已安装的 ID 或 system。未知的 ID 会抛出异常而不更改语言;未更改的选择/有效状态不会再次通知。
  • SelectedLanguageID 是请求的选择;CurrentLanguageID 是解析后的包。系统匹配使用最初捕获的区域设置:精确 ID、父级、同语言候选,然后是英语。中文/英语优先选用 zh-CN/en-US;其他候选按 ID 排序。
  • KnownLanguages 提供 LanguageName 标签和 LanguageID 选择,以及本地化的系统选项。不要恢复固定的英语/中文索引或偏好白名单。
  • 该服务不持久化偏好。在创建 MainWindow AXAML 之前应用相同的启动偏好,并将该存储/快照传递给会话。如果保存的包暂时不可用,则显示英语,同时保留保存的 ID 和其他偏好。
  • 在直接调用 SetLanguage 后,保存不相关的主题/音量偏好时不得重置语言。仅在语言偏好本身更改时应用新选择。

为静态文本使用 Loc

默认的 Avalonia XML 命名空间通过 XmlnsDefinition 注册了 LocExtension,因此无需前缀即可使用 {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>

最后一个示例需要 xmlns:common="using:AegiNext.Desktop.Controls.Common"。复用 IconText 的版式和尺寸设置;IconKey 独立于翻译的键/值来标识图标。适当地迁移 Text、Content、Header、工具提示和辅助功能名称;保留动态内容的业务绑定。

Loc 返回一个可观察绑定,在订阅时立即提供文本,并在语言更改时更新。保留 DataContext。不要捕获目标控件、扫描树、重新引入翻译 Tag 或将实时绑定替换为一次性 Get 赋值。

动态文本和订阅生命周期

播放/暂停、静音、快捷键记录和导出状态保持绑定到其所属的 ViewModel,这些 ViewModel 调用 Get/Format。存储语义键、枚举和格式参数,而不仅仅是最后翻译的字符串。在会话、布局、注册表和设置中复用集中的 LanguageChanged 处理程序;避免重复订阅。

对于编程式控件,保留并释放可观察绑定句柄:

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

Observe 当前是 Desktop 内部的。在 Closed/Dispose 时释放句柄/事件,并先处理替换的状态绑定。提供者仅捕获必要的业务值,如 Views/TrackStyleChangeDialog.cs 中所示。区分临时固定面板分离和最终释放,以便重新附加时仍能接收更新。

语言刷新仅更改呈现:不进行业务提交、项目重建、撤销或丢弃草稿。刷新选择列表,同时保留稳定的 ID、实际选择以及无效的原始输入;忽略框架自动选择作为用户编辑。根据需要复用使用中的 Styles/Effects ChoicesRefreshing/ChoicesRefreshed 守卫。

验证和交付

按照 verification 中受影响的分组进行操作,检查编译后的 AXAML、实时切换、业务状态和发布行为。检查原始 JSON 的键完整性;Get 回退无法证明翻译存在。构建/加载/发布更改需要实际的输出 i18n 目录、包哈希以及从另一个工作目录启动。macOS 包使用 AegiNext.app/Contents/MacOS/i18n/。

报告实际的构建/分析、通过/失败/跳过的测试、资源检查和原生验收。根据当前证据而非历史总数重新计数键/测试。将 Headless 结果与按钮/图标、长文本和平台菜单外观分开。保留范围和无关的工作;使用此技能不授权提交或依赖升级。

相关技能