# CodexBar에 한국어 현지화 추가

- URL: https://soohan.dev/projects/open-source/codexbar-korean-localization
- Category: projects/open-source
- Published: 2026-06-12
- Tags: open-source, swift, macos, localization
- Author: Soohan Park

> 1,040개 문자열을 번역하고 언어 선택기와 테스트를 연결해 CodexBar에 한국어를 추가한 기록.

---

CodexBar는 여러 언어를 지원했지만 한국어 리소스는 없었습니다.
시스템 언어가 한국어여도 앱은 다른 언어로 표시됐고,
설정의 언어 선택기에서도 한국어를 고를 수 없었습니다.

[steipete/CodexBar PR #1460](https://github.com/steipete/CodexBar/pull/1460)에서
한국어를 기존 현지화 구조에 연결했습니다.

## 번역만 추가해서는 끝나지 않았다

새 `ko.lproj/Localizable.strings`에 영어 카탈로그와 동일한 1,040개 키를 추가했습니다.
macOS에서 쓰는 표현을 기준으로 `Settings`는 `설정`, `Refresh`는 `새로 고침`,
`Menu bar`는 `메뉴 막대`처럼 옮겼습니다.

문자열 수보다 신경 쓴 부분은 포맷 지정자였습니다.
`%@`, `%lld`, `%1$@` 같은 지정자와 `\(name)` 보간 값은
번역 뒤에도 원문과 같은 인자를 받아야 합니다.
한국어 어순 때문에 인자의 위치가 달라지는 문장은 위치 지정자를 사용했습니다.

리뷰 중에는 사용량 차트의 접근성 문구에서 일수와 서비스 수의 위치가 뒤바뀔 수 있는 사례가 발견됐습니다.
이를 `%2$d`, `%1$d`로 바로잡고, `7일`과 `3개 서비스`가 각각 올바른 자리에 렌더링되는 테스트를 추가했습니다.

## 앱의 언어로 연결하기

번역 파일과 함께 다음 범위를 수정했습니다.

- `AppLanguage`에 `ko`를 추가하고 설정 화면의 Language Picker와 연결
- 모든 기존 언어 카탈로그에 `language_korean` 이름 추가
- 한국어 시스템 환경에서는 기본 `System` 모드가 `ko`를 선택하도록 기존 로케일 처리와 연동
- 언어 카탈로그 간 키와 포맷 지정자를 비교하는 테스트 대상에 한국어 추가

리소스 디렉터리를 자동으로 번들링하는 구조와 `ko` 로케일을 처리하는 기본 로직은 이미 있어서
`Package.swift`와 `Localization.swift`는 수정하지 않았습니다.

## 검증

- 영어 카탈로그와 한국어 카탈로그의 키 `1,040 / 1,040` 일치
- 누락·추가 키와 포맷 지정자 불일치 0건
- 현지화 테스트 22개 통과
- 격리된 `CODEX_HOME` 환경에서 상태 메뉴 갱신 테스트 13개 통과
- `make check`와 메인테이너 자동 리뷰 통과
- 패키징한 앱에서 한국어 선택 후 메뉴와 일반 설정 화면 렌더링 확인

## 결과

PR은 2026년 6월 12일에 열어 같은 날 병합됐습니다.
최종 변경은 17개 파일, 4개 커밋, `+1,111 / -3`이었고
CodexBar 변경 로그에도 한국어 지원과 기여자 정보가 남았습니다.