Easydict 딥다이브
— 선택한 한 문장이 번역이 되기까지

1프로젝트 한줄 요약

Easydict는 macOS에서 텍스트를 가져와 사전·번역·AI 서비스에 연결하는 통합 작업 도구입니다. 자체적으로 거대한 번역 모델을 학습시키기보다, 사용자의 입력과 여러 엔진 사이를 연결하는 데 집중합니다. 이 저장소의 핵심은 번역 알고리즘보다, 번역까지 이어지는 사용자의 동작을 하나의 흐름으로 만드는 설계입니다.

예를 들어 영어 문서를 읽다가 한 문장을 선택하고 Option + D를 누르면 선택 영역을 읽어 질의 창으로 보냅니다. 텍스트를 선택할 수 없는 이미지라면 Option + S로 화면 일부를 캡처합니다. Apple Vision이 글자를 읽고, 결과를 번역 서비스에 전달합니다. 입력 창의 기본 단축키는 Option + A입니다.

단축키의 실제 기본값은 Easydict/Swift/Feature/Shortcut/Model/ShortcutManager+Default.swift의 setDefaultGlobalShortcutKeys()에서 확인할 수 있습니다. 표의 Objective-C 컨트롤러는 Easydict/objc/ViewController/Window/BaseQueryWindow/EZBaseQueryViewController.m에 있습니다.

2왜 주목받는가

2-1. 번역 사이트를 여는 비용을 줄인다

2026-10-23 분석에서 GitHub Trending Swift Weekly #10으로 선정된 프로젝트입니다. 스타 15,047개와 포크 794개는 관심의 규모를 보여 주지만, 어떤 기능 때문에 순위가 올랐는지까지 증명하지는 않습니다. 아래 이유는 실제 기능과 구현을 바탕으로 한 해석입니다.

번역은 문장을 복사하고, 창을 전환하고, 붙여 넣는 짧은 동작이 반복되는 작업입니다. Easydict는 선택 영역과 화면 캡처를 입력으로 받아 이 반복을 줄입니다. 자주 쓰는 도구의 가치는 한 번의 놀라운 결과뿐 아니라, 매번 반복하던 작은 동작을 얼마나 줄여 주는가에서도 나옵니다.

2-2. 하나의 엔진에 묶이지 않는 구조

README는 20개 이상의 사전·번역·AI·로컬 모델·CLI 서비스를 소개합니다. QueryServiceFactory.swift의 등록 목록은 29개 항목입니다. 여기에는 번역 공급자뿐 아니라 SummaryService와 PolishingService 같은 작업도 포함됩니다. 이를 모두 서로 다른 번역 회사 29곳으로 세면 안 됩니다.

Apple Dictionary와 MDict를 통한 로컬 사전 조회, Apple 시스템 번역, OpenAI·Gemini·Claude 같은 원격 서비스, Ollama, CLI 기반 서비스가 같은 앱에 공존합니다. 이용 가능한 언어·요금·로그인 조건은 서비스마다 다릅니다. 여러 결과를 모으는 구조가 모든 공급자의 품질이나 가용성을 보장하지는 않습니다.

이 비교는 작업 흐름의 차이입니다. 번역 정확도나 응답 속도를 측정한 경쟁 제품 벤치마크는 아닙니다. README는 Bob과 Saladict에서 영감을 받았고 초기 버전은 Bob 기반이라고 설명합니다. 그 사실만으로 현재 제품 간 우열을 정할 수는 없습니다.

2-3. 학습용으로 흥미로운 이유: 제품의 성장 흔적

이 저장소에는 SwiftUI 화면 옆에 기존 AppKit·Objective-C 창이 남아 있고, 서비스 계층에는 콜백 API와 async/await가 함께 있습니다. @objc(EZQueryService)처럼 Swift 클래스에 기존 Objective-C 이름을 유지하는 코드도 보입니다. 전면 재작성 없이 제품을 발전시키는 현실적인 사례입니다.

Claude Code·Codex CLI·GitHub Copilot 연동은 번역 요청의 실행 경로를 넓힙니다. 다만 이 앱의 중심은 여전히 사전·번역 작업입니다. CLI를 연결했다는 이유로 범용 코딩 에이전트 플랫폼이라고 이해할 필요는 없습니다.

3기술 스택 전체 지도

Easydict의 기본 실행 단위는 macOS 앱 프로세스입니다. 화면을 프론트엔드, 질의·저장·OCR을 백엔드 역할로 나누어 볼 수 있지만, 웹 서비스처럼 항상 별도 서버를 배포하는 구조는 아닙니다. 이 앱에서는 네이티브 UI와 처리 로직이 같은 프로세스에 있고, 외부 번역 API와 선택적 HTTP 서버가 그 경계를 넓힙니다.

3-1. 프론트엔드: SwiftUI와 AppKit을 함께 쓴다

Swift Package Manager 버전은 Easydict.xcworkspace/xcshareddata/swiftpm/Package.resolved에서, Masonry 버전은 Podfile.lock에서 확인했습니다. 시스템 프레임워크에는 별도의 패키지 버전 번호를 붙이지 않고 macOS 가용 조건을 확인해야 합니다.

화면을 모두 웹으로 그리지도 않습니다. Easydict/Swift/Feature/Markdown/MarkdownRenderer.swift는 Markdown을 NSAttributedString으로 바꿉니다. 반면 사전 계층은 HTML 결과도 다룹니다. 결과의 종류에 맞추어 표시 경로가 달라지는 셈입니다.

3-2. 백엔드 역할: 질의·네트워크·인식·저장

QueryRecordManager.swift는 이력과 즐겨찾기를 Defaults 키로 관리하고 이력 상한을 1000으로 둡니다. VocabularyNotebookService.swift는 활성화된 경우 words.jsonl에 한 줄씩 기록합니다. 잠금 파일의 leveldb 같은 전이 의존성이 있다고 앱의 질의 이력을 LevelDB에 저장한다고 해석하면 틀립니다.

OpenAIStreamTransport는 stream 메서드에서 URLSession으로 전송하며, makeRequest가 만드는 요청의 제한 시간은 AppConstants.llmRequestTimeoutInterval = 60초를 참조합니다. SDK를 가져왔어도 전송·응답 검증을 제품 요구에 맞게 직접 감쌀 수 있다는 사례입니다.

3-3. 인프라·빌드: 두 패키지 관리 체계의 공존

Easydict.xcodeproj/project.pbxproj가 앱 타깃·소스·프레임워크·빌드 설정을 연결합니다. CocoaPods까지 포함하는 진입점은 Easydict.xcworkspace입니다. 이 프로젝트에는 앱을 정의하는 최상위 Package.swift가 없으며, BuildTools/Package.swift는 개발 도구용입니다.

.github/workflows/codeql.yml은 Swift를 수동 빌드 모드로 분석합니다. 실행기 레이블은 xcode-27이고 Xcode·macOS 버전이 27.*인지 검사하며, 빌드에 ARCHS=arm64를 지정합니다. 이는 설정된 분석 환경이지 모든 플랫폼에서 테스트가 통과했다는 결과 보고는 아닙니다.

배포 절차는 .agents/skills/release-easydict/scripts/의 release-build.sh, release-package.sh, release-appcast.py 등에 나뉩니다. Archive·Developer ID 서명·공증·DMG·업데이트 피드가 각각 다루어집니다. 일반 앱 학습을 시작할 때 이 배포 절차부터 이해할 필요는 없습니다.

4아키텍처 심화 분석

앱 진입점은 Easydict/App/EasydictApp.swift의 EasydictCmpatibilityEntry.main()입니다. 경로 마이그레이션·인자 처리·충돌 기록·OCR 예열 등을 준비한 뒤 EasydictApp.main()으로 넘어갑니다. SwiftUI의 @NSApplicationDelegateAdaptor는 기존 AppDelegate와 연결하고, 메뉴 막대와 설정 화면은 SwiftUI Scene으로 구성합니다.

일반 질의의 순서는 컨트롤러의 startQueryText:actionType: → queryCurrentModel → 필요하면 언어 감지 → queryAllSerives: → queryWithModel:service:입니다. queryAllSerives라는 철자는 소스 그대로입니다. 서비스마다 비동기 요청을 시작하므로, 한 서비스가 끝날 때까지 모두 기다린 뒤 다음 서비스를 시작하는 구조가 아닙니다.

4-1. 팩토리와 템플릿 메서드: 공급자를 바꿀 수 있는 이유

Easydict/Swift/Service/Model/QueryServiceFactory.swift는 서비스 식별자와 클래스의 등록부입니다. service(withTypeId:)는 식별자를 분해하고 알맞은 클래스를 찾아 init()한 뒤 인스턴스의 uuid를 지정합니다. # 뒤의 UUID를 분리하는 구조는 같은 종류의 사용자 정의 서비스를 여러 개 구성하는 데 쓰입니다. 일반 질의에서는 컨트롤러에 이미 구성된 서비스 목록을 순회합니다.

// QueryServiceFactory.swift: 등록 목록 중 일부
.init(.appleDictionary, AppleDictionary.self,
      "apple_dictionary", apiKeyRequirement: .none),
.init(.openAI, OpenAIService.self, "openai_translate"),
.init(.customOpenAI, CustomOpenAIService.self,
      "custom_openai", allowsMultipleInstances: true),

상위 클래스 QueryService의 startQuery(_:)는 모델 연결 → 입력·언어 추출 → 공통 전처리 순서로 진행하고, 전처리에서 완료되지 않으면 translate(_:from:to:)를 호출합니다. 하위 클래스는 마지막 번역 동작을 재정의합니다. 이처럼 공통 절차는 상위 클래스가 정하고 일부 단계는 하위 클래스에 맡기는 방식이 템플릿 메서드 패턴입니다.

이 프로젝트의 공급자 확장은 추상 프로토콜만으로 이루어지지 않습니다. 실제 중심은 NSObject를 상속하는 QueryService 클래스와 재정의 메서드입니다. 코드에 없는 프로토콜 기반 구조를 가정하기보다 required init, override, @objcMembers의 쓰임을 함께 보세요.

4-2. 어댑터: 서로 다른 응답을 같은 스트림으로

StreamService 계층은 조금씩 도착하는 AI 응답을 처리합니다. Easydict/Swift/Service/OpenAI/StreamService+AsyncStream.swift는 문자열 조각을 ChatStreamResult 또는 누적 QueryResult로 바꿉니다. StreamService+UpdateResult.swift의 throttleUpdateResultText는 기본 간격 0.3초로 갱신 빈도를 제어합니다.

OpenAIStreamTransport.swift의 stream(query:url:apiKey:onResult:)는 HTTP 상태 코드를 먼저 검사하고, 정상 응답의 MIME 유형이 text/event-stream인지 확인합니다. completedEvent(from:)는 빈 줄 경계를 찾고, decodeEvent(dataLines:)는 data: 줄을 모아 JSON으로 해석합니다. [DONE]은 종료 신호입니다.

네트워크에서 한 번 받은 데이터가 JSON 하나와 정확히 일치한다고 가정하면 안 됩니다. 한 이벤트가 여러 조각으로 나뉘거나 여러 줄의 데이터로 표현될 수 있습니다. 이 전송 계층은 바이트 수신과 의미 있는 이벤트의 경계를 구분합니다. 실패 응답 본문을 읽는 상한도 64 * 1024바이트로 둡니다.

// AsyncThrowingStream 안에서 사용하는 정리 구조를 축약한 예시
AsyncThrowingStream { continuation in
    let task = Task {
        do {
            for try await content in contentStream {
                continuation.yield(content)
            }
            continuation.finish()
        } catch {
            continuation.finish(throwing: error)
        }
    }
    continuation.onTermination = { _ in task.cancel() }
}

yield는 “다음 조각이 왔다”, finish는 “더 이상 오지 않는다”라는 신호입니다. onTermination은 소비가 끝났을 때 내부 작업도 취소하도록 연결합니다. 스트림을 만드는 것과 내부 작업의 수명을 끝까지 관리하는 것은 함께 설계해야 합니다.

4-3. 세대 번호와 협력적 취소: 오래된 답이 새 화면을 덮지 않게

사용자가 A를 질의한 직후 B를 질의했는데 A의 응답이 늦게 도착할 수 있습니다. 단순히 마지막에 도착한 답을 표시하면 B의 창에 A의 번역이 나타납니다. 비동기 UI에서는 요청을 중단하는 것과, 이미 도착 중인 오래된 결과를 무시하는 것을 함께 처리해야 합니다.

QueryService.resetServiceResult()는 resultGeneration을 증가시킵니다. 스트림을 시작할 때 기억한 targetGeneration과 현재 값을 비교하고, 다르면 결과 갱신을 버립니다. NSRecursiveLock으로 세대 확인과 결과 변경을 함께 보호하며, UI 콜백 직전에도 세대를 다시 검사합니다.

// StreamService+UpdateResult.swift: 오래된 스트림 차단
if let targetGeneration, targetGeneration != resultGeneration {
    return
}

// QueryModel.swift: 등록을 제거한 다음, 잠금 밖에서 취소 호출
func stopServiceRequest(_ serviceType: String) {
    let stopBlock = stopBlockLock.withLock {
        stopBlockDictionary.removeValue(forKey: serviceType)
    }
    stopBlock?()
}

Easydict/Swift/Model/QueryModel.swift의 잠금은 취소 콜백 등록부를 보호합니다. 모델의 모든 필드가 스레드 안전하다는 뜻은 아닙니다. stopAllService()도 현재 콜백을 배열로 옮기고 등록부를 비운 뒤 잠금을 풀어 호출합니다. 콜백이 다시 새 콜백을 등록해도 그 등록을 지워 버리지 않도록 하는 설계입니다.

EasydictTests/Model/QueryModelCancellationTests.swift의 singleStopPreservesReentrantRegistration()과 concurrentStopsInvokeCallbackOnce()가 이 동작의 의도를 보여 줍니다. 전자는 취소 중 재등록을, 후자는 개별 취소와 일괄 취소가 겹치는 경우를 다룹니다. 테스트 소스를 읽으면 복잡해 보이는 순서가 왜 필요한지 알 수 있습니다.

4-4. 파이프라인과 호환 계층: OCR은 글자 인식 다음이 길다

Easydict/Swift/Service/Apple/AppleOCREngine/AppleOCREngine.swift의 recognizeText는 이미지 확인 → QR 해독 → Vision OCR → 언어 판단 → 텍스트 병합으로 이어집니다. OCRTextProcessor.setupOCRResult는 관측 결과를 받아 가로 영역과 구역을 분석하고, 줄·문단을 합쳐 최종 문자열을 만듭니다.

짧은 문장은 언어를 확신하기 어렵습니다. 코드의 hasEnoughLength는 mergedText.count > 50이고, requiresAccurateRecognition 기본값은 false입니다. 여러 언어로 다시 읽는 경로가 있어도 기본 호출마다 반드시 수행되지는 않습니다. AppleService.ocr는 이 옵션을 별도로 켜지 않고 호출합니다.

또한 현대 Vision OCR 메서드는 @available(macOS 15.0, *)로 선언되어 있지만, 실제 선택 조건은 #available(macOS 26.0, *)입니다. 코드 주석은 호환 문제에 따른 보수적 선택이라고 설명합니다. API가 제공되는 OS 버전과 앱이 실제 사용하기 시작하는 버전은 다를 수 있습니다.

커밋 69600ed의 QR 경로는 동기 Vision 작업을 DispatchQueue.global(qos: .utility)에 보내고 명시적 QoS로 실행합니다. 호출자는 continuation에서 기다리며, 작업 전후의 Task.checkCancellation()로 취소를 전달합니다. 동기 Vision 호출이 즉시 중단된다는 뜻은 아니며, 완료되어도 취소된 결과를 버리는 방식입니다.

기존 OCR API를 비동기 코드로 연결하는 ContinuationGate는 잠금으로 continuation을 한 번만 꺼냅니다. 완료 콜백과 perform()의 오류가 모두 발생해도 두 번 resume하지 않게 합니다. 실패 경로까지 포함한 “정확히 한 번 완료”는 콜백 변환에서 중요한 계약입니다.

5디렉토리 구조 해부

위 트리의 첫 번째 Easydict/는 앱 소스 디렉토리이며, 그 아래의 테스트·프로젝트·문서 디렉토리는 저장소 루트에 있습니다. Service는 특정 엔진이 요청을 처리하는 곳, Feature는 사용자가 어떤 작업을 하는지 표현하는 곳, Utility는 여러 기능이 공유하는 도구로 읽으면 됩니다.

모든 파일이 이 분류에 완벽하게 들어맞지는 않습니다. 예를 들어 이력을 관리하는 QueryRecordManager.swift는 Easydict/Swift/View/SettingView/Tabs/Model/에 있습니다. 디렉토리 이름만 보고 저장 로직이 없다고 결론 내리기보다, 타입과 호출자를 함께 검색하세요.

5-1. 직접 센 코드 규모

집계 기준: 앱은 Easydict/, 테스트는 EasydictTests/ 아래의 해당 확장자가 대상입니다. 줄 수는 개행 문자 기준이며 주석·빈 줄을 포함합니다. 앱 내부 Easydict/objc/Libraries/의 복사된 라이브러리도 포함하고, Pods/·문서·이미지 등 다른 확장자의 리소스·외부 SwiftPM 소스는 제외합니다. 헤더에는 C 스타일 선언도 섞일 수 있습니다.

# 저장소 루트에서 규모를 확인하는 읽기 전용 명령 예시
find Easydict -type f -name '*.swift' -exec wc -l {} +
find Easydict -type f -name '*.m' -exec wc -l {} +
find EasydictTests -type f -name '*.swift' -exec wc -l {} +

앱의 위 다섯 확장자는 합계 88,498줄입니다. 테스트 줄 수는 학습할 사례의 양을 보여 줄 뿐, 코드 커버리지나 신뢰성을 직접 나타내는 지표는 아닙니다. 이 표는 커밋 69600ed의 코드 규모를 나타내며, 개발 속도나 주간 증가량을 뜻하지 않습니다.

5-2. 처음 읽을 때 권하는 순서

1. EasydictApp.swift에서 앱 시작과 메뉴·설정 화면을 찾습니다.
2. QueryModel.swift와 QueryResult.swift에서 입력·출력을 구분합니다.
3. QueryServiceFactory.swift에서 관심 있는 서비스 하나를 고릅니다.
4. AppleService.swift 또는 OllamaService.swift에서 구체적인 실행을 읽습니다.
5. 마지막으로 EZBaseQueryViewController.m에서 화면과 이 객체들이 연결되는 곳을 확인합니다.

6학습 포인트 (기술별)

처음부터 모든 공급자의 API 요청 코드를 읽으면 차이만 늘어나고 공통 구조는 잘 보이지 않습니다. 같은 입력이 어느 경계에서 어떤 형태로 바뀌는지 추적하면, 배운 설계를 다른 앱에도 옮길 수 있습니다.

6-1. Swift와 Objective-C 상호운용

QueryService.swift의 @objc(EZQueryService)와 QueryModel.swift의 Objective-C 노출을 살펴보세요. 기존 컨트롤러는 EZQueryService·EZQueryModel이라는 이름으로 Swift 객체를 사용합니다. Easydict/App/Easydict-Bridging-Header.h는 반대 방향으로 Objective-C 선언을 Swift에 연결합니다.

작은 실습: Swift 클래스 하나의 Swift 이름·Objective-C 이름·노출 메서드를 표로 적어 보세요. 왜 스트림 같은 Swift 전용 API에 @nonobjc가 붙고, 화면에는 콜백 기반 메서드를 따로 제공하는지도 설명해 봅니다.

6-2. async/await와 UI 격리

QueryService.startQueryStream(_:completionHandler:)는 스트림을 순회하고 MainActor.run 안에서 화면용 콜백을 호출합니다. SelectionWorkflow.getSelectedTextSnapshot의 완료 콜백에는 @MainActor가 선언되어 있지 않습니다. 같은 “콜백”이라도 실행 문맥의 계약이 다릅니다.

작은 실습: 네트워크 대기, 문자열 누적, 결과 상태 변경, UI 표시 네 단계를 다른 색으로 표시해 보세요. async라는 키워드만 보고 무거운 계산이 자동으로 백그라운드에서 처리된다고 생각하지 않는 것이 출발점입니다. 비동기 실행과 스레드의 관계는 Swift 공식 동시성 문서에서 이어서 읽을 수 있습니다.

6-3. OCR 후처리와 휴리스틱

OCRConstants.swift에는 들여쓰기 판단용 1.8글자, 일반 줄 간격 상한 비율 1.2, 중국어 시의 한 줄 최대 글자 수 12.0, 영어 시의 한 줄 최대 단어 수 7.0 등이 있습니다. 이는 하드웨어 요구량이 아니라 레이아웃 판단을 위한 기준값입니다.

작은 실습: 문단·시·두 단으로 된 문서를 각각 골라 줄바꿈을 유지해야 하는 이유를 적어 보세요. OCRTextProcessingTests.swift, OCRTextProcessingChineseTests.swift, OCRPunctuationTests.swift의 입력·기대값을 비교하면 규칙이 어떤 문장을 보호하려는지 보입니다.

6-4. 바이너리 파일과 제한된 메모리

Easydict/Swift/Service/Dictionary/MDict/MDictReader/MDictReader.swift는 MDX·MDD 사전 형식을 다룹니다. RecordBlockRange는 압축된 데이터와 압축 해제된 데이터의 위치를 저장하고, 필요한 레코드 블록을 찾는 데 사용됩니다. 상수에는 단일 압축 해제 블록 크기 상한 256 * 1024 * 1024바이트, 키 블록 캐시 16개, 레코드 블록 캐시 8개·50MiB가 보입니다.

작은 실습: 사전을 통째로 메모리에 올리는 방식과 필요한 블록만 읽는 방식의 비용을 비교하세요. MDictSearchIndex.candidates(for:limit:)는 기본 후보 8개를 접두어 → 부분 문자열 → 편집 거리 순서로 찾습니다. 편집 거리 상한은 2입니다. 정확한 검색과 비슷한 단어 제안을 서로 다른 경로로 나누는 이유를 배울 수 있습니다.

6-5. 저장과 종료 시점의 신뢰성

VocabularyNotebookService.append는 현재 화면에서 계속 바뀌는 입력보다 결과에 붙은 result.queryText를 기록에 사용합니다. 기록 작업은 전용 직렬 큐에 넣고, flush()는 앞서 들어온 쓰기가 끝나기를 기다립니다. 앱 종료 알림에서 동기적으로 flush()하는 코드가 EasydictApp.swift에 있습니다.

작은 실습: “번역이 끝남 → 파일 기록 예약 → 앱 종료” 순서를 그려 보세요. 예약만 하고 종료하면 왜 마지막 단어를 잃을 수 있는지, 마지막 줄에 개행이 없는 JSONL 파일에 바로 덧붙이면 왜 두 기록이 붙어 버리는지 설명해 봅니다.

6-6. 테스트에서 요구사항을 역으로 읽기

테스트의 입력·기대값은 요구사항을 이해하는 단서입니다. 테스트가 존재한다는 사실만으로 실행 성공률이나 코드 커버리지를 판단할 수는 없습니다.

7하드웨어 / 시스템 요구사항

앱의 공식 최소 RAM·디스크·GPU 수치는 프로젝트 문서에 명시되어 있지 않습니다. 따라서 8GB나 16GB를 공식 최소 사양으로 적을 근거는 없습니다. CodeQL 설정의 arm64도 분석 대상 아키텍처이며, 배포 파일의 Intel 호환성을 보장하는 값은 아닙니다.

로컬 OCR을 쓰는 데 필요한 자원과, 로컬 LLM을 실행하는 데 필요한 자원은 별개입니다. 기본 OCR은 Vision을 이용합니다. 반면 Ollama의 모델 크기·정밀도·문맥 길이에 따른 메모리 요구량은 별도로 확인해야 합니다. OllamaService의 기본 주소는 http://localhost:11434/v1/chat/completions이며, 앱이 자체 추론 엔진을 내장했다는 뜻은 아닙니다.

7-1. 오프라인 기능을 읽을 때 확인할 세 가지

1. 인식: 이미지의 글자는 기본적으로 시스템 Vision이 읽습니다.
2. 번역: Apple 오프라인 번역은 기본값이 꺼져 있습니다. macOS 15+와 언어팩·옵션 조건을 확인해야 합니다.
3. 결과의 이동: 뒤이어 원격 서비스를 실행하면 인식된 텍스트가 해당 서비스로 전달될 수 있습니다.

Defaults.Keys+Extension.swift의 enableAppleOfflineTranslation은 false입니다. AppleService.translateAsync는 조건을 만족할 때 Translation 경로를 사용하고, 그렇지 않으면 AppleScript로 단축어를 호출합니다. 두 경로의 준비 조건을 하나로 뭉뚱그리지 마세요.

7-2. 개발 도구 버전과 실행 OS 버전은 다른 축

사용 가이드는 Xcode 16+를 안내하지만 CodeQL 워크플로는 Xcode 27·macOS 27을 검사합니다. 앱은 macOS 13을 배포 대상으로 설정합니다. 실행 가능한 OS, 빌드에 쓰는 SDK·컴파일러, CI가 선택한 환경은 서로 다른 값입니다. 이 설정만으로 Xcode 16에서 현재 의존성까지 모두 빌드된다고 보장할 수는 없습니다.

또한 .swift-version의 5.9와 SWIFT_VERSION = 5.0은 실제 swiftc --version 측정값이 아닙니다. 저장소에 Swift 6의 엄격한 동시성 모드가 전면 적용되었다고 해석해서도 안 됩니다.

8직접 해볼 수 있는 실습 과제

실습은 원본 저장소와 분리한 학습용 예제에서 진행하는 구성을 권합니다. 앞의 두 과제는 소스 읽기만으로 완성할 수 있고, 뒤의 과제는 가짜 응답을 사용해 API 키와 유료 호출 없이 구현할 수 있습니다. 완료 기준을 눈에 보이는 산출물로 정하면, 코드를 읽었다는 느낌을 넘어 실제로 이해했는지 확인할 수 있습니다.

## 오늘 배운 것
**아직 도착 중인 답변**
```swift
let count = 3

// 학습용 데이터 형태의 예시. 원본 타입의 복사본은 아닙니다.
struct TextBox {
    let text: String
    let x: Double
    let y: Double
    let width: Double
    let height: Double
}

9관련 기술 심화 학습 로드맵

하루에 새 라이브러리를 하나씩 추가하는 방식보다, 입력과 결과 사이의 계약을 점차 넓히는 순서가 초보자에게 적합합니다. 작은 동기 함수에서 시작해 비동기 결과, 취소, 파일 기록, 시스템 통합 순으로 확장해 보세요.

매주 “함수가 무엇을 받는가, 무엇을 돌려주는가, 실패하면 누가 처리하는가”를 세 줄로 적으세요. 셋 중 하나라도 불분명하면 전체 파일을 더 읽기 전에 호출자와 결과 사용 지점을 찾아보는 편이 좋습니다.

9-1. 관심사에 따른 다음 갈림길

• macOS 앱 개발: SwiftUI의 상태·Scene → AppKit 창·이벤트 → 접근성·권한 → Objective-C 상호운용 순으로 확장합니다.
• AI 클라이언트: HTTP → SSE → 스트림 수명 → 공급자별 설정 → CLI 프로세스·인증 경계로 확장합니다.
• 문서 처리: Vision 관측 결과 → 좌표·읽기 순서 → 언어별 병합 규칙 → 실제 문서의 실패 사례 수집으로 확장합니다.
• 파일·검색: MDict 헤더·바이트 순서 → 블록 위치 → 제한된 캐시 → 편집 거리 기반 후보 검색으로 확장합니다.

CLI 쪽을 더 읽는다면 CodexCLIService.contentStreamTranslate가 좋은 입구입니다. 이 커밋에는 로컬 codex exec --json 경로와 관리형 App Server 경로가 함께 있습니다. 주석상 관리형 경로는 프로세스를 재사용하면서 번역마다 독립적인 임시 대화를 만들도록 설계되었습니다. 로컬 프로세스를 호출하는 것과 모델 추론이 로컬에서 일어나는 것은 구분해야 합니다.

10핵심 키워드 사전

11참고 링크

11-1. 공식 저장소와 사용 문서

• Easydict 공식 저장소 — 소개·소스·기여 창구.
• 2.24.0 릴리스 — 2026-09-27 공개 릴리스.
• 전체 사용 가이드 — 설치·단축키·권한·서비스 설정.
• 서비스별 접근 조건 — 키·로그인·로컬 도구의 조건.
• Apple 시스템 번역 사용법 — 오프라인 번역과 단축어 경로.
• GPL-3.0 라이선스 원문 — 코드 활용·재배포 전에 확인할 문서.

11-2. 해설의 중심이 된 소스

• 앱 진입점과 생명주기 — 메뉴·설정·종료 시 기록 정리.
• 서비스 팩토리 · 공통 서비스 계층 — 등록·실행·세대 관리.
• QueryModel · 취소 동작 테스트 — 잠금과 재진입 처리.
• SSE 전송 · 스트리밍 결과 갱신 — 이벤트 경계·오류·갱신 빈도.
• OCR 엔진 · OCR 후처리 — 시스템 API와 문단 복원의 경계.
• 언어 감지·OCR 연결 — 공개 진입점과 대체 경로 비교.
• HTTP 라우트 — 같은 서비스 계층을 API에서 재사용.
• SwiftPM 잠금 파일 · CocoaPods 잠금 파일 · CodeQL 설정 — 버전·분석 환경의 근거.

11-3. 관련 기술의 공식 문서

• Swift 동시성 — 비동기 함수·작업·취소·격리의 기본 개념.
• SwiftUI · AppKit — 네이티브 화면과 시스템 연결.
• Vision RecognizeTextRequest · Translation — 시스템 인식·번역 API.
• Vapor 라우팅 — HTTP 메서드·경로·본문 수집 한도 설정.
• Swift Async Algorithms — 비동기 시퀀스 처리 도구.
• MacPaw OpenAI Swift 라이브러리 · Sparkle 문서 — API 모델과 앱 업데이트 기술.

현재 상태 (2026-10-23 확인)