Communitygithub.com

raphaelstuart/Aegisub-NEXT

외부 JSON 언어 팩, 공유 지역화 서비스 및 라이브 Avalonia Loc 바인딩을 사용하여 AegiNext UI 지역화를 추가, 변경, 검토 또는 디버그합니다. 번역된 컨트롤, 동적 뷰모델 텍스트, 메뉴, 창 제목, 언어 기본 설정 및 언어 리소스 패키징에 사용하세요. 자막 콘텐츠, 사용자 프리셋 이름 및 이펙트 스크립트 구문은 비즈니스 데이터로 유지됩니다.

Aegisub-NEXT란 무엇인가요?

이 스킬은 Aegisub-NEXT(AegiNext) 프로젝트의 UI 지역화(로컬라이제이션) 시스템을 다루는 방법을 안내합니다. 개발자는 외부 JSON 언어 팩과 `I18n/` 디렉토리에 위치한 공유 `Localization` 서비스를 통해 모든 UI 텍스트를 추가, 수정 및 관리할 수 있습니다. 이 시스템은 정적 XAML 레이블(`{Loc Key=...}` 마크업 확장 사용)과 동적 뷰모델 텍스트(코드에서 `Get`/`Format` 호출)를 모두 지원하며, 언어 변경 시 UI가 자동으로 업데이트됩니다. 주로 Claude Code, Cursor, Codex와 같은 에이전트 기반 개발 도구와 함께 사용되도록 설계되었으며, 자막 데이터나 사용자 프리셋 같은 비즈니스 데이터는 건드리지 않고 인터페이스 텍스트만 지역화합니다. 또한 언어 팩 스키마, 서비스 계약(초기화, 키 조회, 언어 전환 규칙), 빌드 및 배포 시 고려사항을 상세히 설명하여 정확하고 일관된 지역화 작업을 보장합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/raphaelstuart/Aegisub-NEXT/tree/HEAD/.agents/skills/aeginext-localization

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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와 같이 일반 서비스를 확장하지 않고 기능에 속합니다.

서비스 및 기본 설정 계약

  • Initialize(directory)를 AXAML을 로드하기 전에 UI 스레드에서 한 번 호출하고, 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는 observable 바인딩을 반환하며, 구독 시 즉시 텍스트를 제공하고 언어 변경 시 업데이트됩니다. DataContext를 유지하십시오. 대상 컨트롤을 캡처하거나, 트리를 스캔하거나, 번역 태그를 다시 도입하거나, 라이브 바인딩을 일회성 Get 할당으로 대체하지 마십시오.

동적 텍스트 및 구독 수명

재생/일시 정지, 음소거, 단축키 녹화 및 내보내기 상태는 Get/Format을 호출하는 소유 ViewModel에 계속 바인딩됩니다. 마지막 번역된 문자열만이 아니라 의미상의 키, 열거형 및 형식 인수를 저장하십시오. 세션, 레이아웃, 레지스트리 및 설정에서 중앙 집중식 LanguageChanged 핸들러를 재사용하고 중복 구독을 피하십시오.

프로그래매틱 컨트롤의 경우 observable 바인딩 핸들을 유지하고 해제하십시오:

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 결과를 버튼/아이콘, 긴 텍스트 및 플랫폼 메뉴 모양과 분리하십시오. 범위와 관련 없는 작업을 유지하십시오. 이 스킬을 사용한다고 해서 커밋이나 종속성 업그레이드가 허가되는 것은 아닙니다.

관련 스킬