project-auto-wizard 0.13.2 → 0.14.0

package/payload/scripts/changelog_manager.py

@@ -2,22 +2,22 @@
 """
 changelog_manager.py
 
-통합 체인지로그 매니저 스크립트.
+Unified changelog manager script.
 
-서브커맨드:
-  - update-from-summary: 릴리즈 요약 Markdown을 파싱하여 CHANGELOG.json 갱신
-  - generate-md        : CHANGELOG.json을 기반으로 CHANGELOG.md 재생성
-  - export             : 특정 버전의 릴리즈 노트를 생성하여 stdout 또는 파일로 저장
-  - ai-summary         : 커밋 목록으로부터 AI(또는 규칙 기반 폴백) 릴리즈 요약 생성
+Subcommands:
+  - update-from-summary: parse the release summary Markdown and update CHANGELOG.json
+  - generate-md        : regenerate CHANGELOG.md from CHANGELOG.json
+  - export             : build the release notes of one version and write them to stdout or a file
+  - ai-summary         : build a release summary from a commit list (language model, or the rule-based fallback)
 
-사용 예:
+Examples:
   python3 changelog_manager.py update-from-summary
   python3 changelog_manager.py generate-md
   python3 changelog_manager.py export --version 0.0.2 --output release_notes.txt
   python3 changelog_manager.py ai-summary --commits-file commits.txt --version 1.2.3 --output summary.md
 
-입력 파일:
-  - pr_body.md: GitHub PR body (Markdown 형식)
+Input file:
+  - pr_body.md: GitHub PR body (Markdown)
 """
 
 from __future__ import annotations
@@ -35,42 +35,44 @@ import urllib.error
 import urllib.request
 
 import issue_helper
+from messages import SUPPORTED, t, tn, template, use_utf8_output
 
 
-# ----------------------------- 공통 유틸 -----------------------------
+# ----------------------------- Common utilities -----------------------------
 
 def _normalize_text(text: str) -> str:
-    """텍스트 정규화: HTML 엔티티 디코딩 및 공백 정리."""
+    """Normalize text: decode HTML entities and trim whitespace."""
     return html.unescape(text).strip()
 
 
 def _clean_summary_noise(text: str) -> str:
     """
-    Summary 텍스트에서 불필요한 노이즈 제거.
+    Remove unwanted noise from summary text.
 
-    제거 대상:
-    1. HTML 주석 (<!-- ... -->)
-    2. 남은 HTML 태그
-    3. 연속된 빈 줄
+    Removed:
+    1. HTML comments (<!-- ... -->)
+    2. Remaining HTML tags
+    3. Runs of blank lines
     """
     if not text:
         return text
 
-    # 1. HTML 주석 제거
+    # 1. Remove HTML comments
     text = re.sub(r'<!--.*?-->', '', text, flags=re.DOTALL)
 
-    # 2. 남은 HTML 태그 제거
+    # 2. Remove remaining HTML tags
     text = re.sub(r'<[^>]+>', '', text)
 
-    # 3. 연속된 빈 줄 정리 (3개 이상 → 2개)
+    # 3. Collapse runs of blank lines (3 or more -> 2)
     text = re.sub(r'\n{3,}', '\n\n', text)
 
     return text.strip()
 
 
 def _strip_version_headings(text: str) -> str:
-    """요약 본문의 `## [1.2.3]` 버전 헤더 줄을 뺀다 — CHANGELOG.md는 릴리스마다
-    자체 헤더를 쓰므로, 남겨 두면 커밋이 없는 릴리스에서 헤더가 두 번 찍힌다."""
+    """Drop `## [1.2.3]` version heading lines from the summary body — CHANGELOG.md
+    writes its own heading per release, so keeping them would print the heading twice
+    for a release without commits."""
     if not text:
         return text
     kept = []
@@ -83,52 +85,108 @@ def _strip_version_headings(text: str) -> str:
 
 
 def _make_safe_key(title: str, idx: int) -> str:
-    """카테고리 제목을 안전한 키로 변환."""
-    safe_key = re.sub(r'[^a-zA-Z0-9가-힣]', '_', title.lower()).strip('_')
+    """Convert a category title into a safe key."""
+    # \uac00-\ud7a3 is the Hangul syllable block; titles in either language keep their letters
+    safe_key = re.sub(r'[^a-zA-Z0-9\uac00-\ud7a3]', '_', title.lower()).strip('_')
     return safe_key if safe_key else f"category_{idx}"
 
 
-# ----------------------- Markdown 파서 (통합) -----------------------
+# Category keys stored in CHANGELOG.json for the standard sections, so the same category
+# is one key whatever language the notes were written in.
+_STANDARD_CATEGORY_KEYS = ('breaking', 'feat', 'fix', 'perf', 'docs', 'refactor', 'test', 'deps', 'changes', 'wip')
+
+
+def _standard_key_by_title() -> dict:
+    """Safe-key form of every standard section title (all supported languages) -> fixed category key."""
+    lookup: dict[str, str] = {}
+    for lang in SUPPORTED:
+        for bucket in _STANDARD_CATEGORY_KEYS:
+            title = template(f"changelog.section_{bucket}", lang).lstrip('#').strip()
+            lookup[_make_safe_key(title, 0)] = bucket
+    return lookup
+
+
+def _category_key(title: str, idx: int) -> str:
+    """Storage key for a category: a fixed key for standard sections in any language, else the safe title key."""
+    safe_key = _make_safe_key(title, idx)
+    return _standard_key_by_title().get(safe_key, safe_key)
+
+
+def _category_display_title(key: str, stored_title: str) -> str:
+    """Heading to show: standard categories follow the current language, custom ones keep their own title."""
+    if key in _STANDARD_CATEGORY_KEYS:
+        return t(f"changelog.section_{key}").lstrip('#').strip()
+    return stored_title or key
+
+
+def _normalize_parsed_changes(parsed) -> dict:
+    """Read parsed_changes into {fixed key: {'title', 'items'}}.
+
+    Releases stored before keys became language-independent may hold the same category under
+    several keys (`breaking_changes`, a Korean title key, ...); those are merged here by title.
+    Entries may also be a bare item list (very old format), whose key doubles as the title."""
+    result: dict[str, dict] = {}
+    if not isinstance(parsed, dict):
+        return result
+    for raw_key, entry in parsed.items():
+        if isinstance(entry, dict):
+            title = _normalize_text(str(entry.get('title') or '')) or _normalize_text(str(raw_key))
+            items = entry.get('items') or []
+        elif isinstance(entry, list):
+            title = _normalize_text(str(raw_key))
+            items = entry
+        else:
+            continue
+        key = _category_key(title, len(result))
+        target = result.setdefault(key, {'title': title, 'items': []})
+        # Only items already collected from an earlier entry are skipped; repeats inside one entry stay as stored
+        seen = set(target['items'])
+        target['items'].extend(str(it) for it in items if it and str(it) not in seen)
+    return result
+
+
+# ----------------------- Markdown parser (unified) -----------------------
 
 def _parse_summary_markdown(md_content: str) -> dict:
     """
-    릴리즈 요약 Markdown을 카테고리/항목으로 파싱.
+    Parse release summary Markdown into categories/items.
 
-    3단계 폴백 전략:
-    1. 섹션 파싱 (AI 엔진 체인·규칙 기반 폴백이 실제로 생성하는 형식)
-    2. 관대한 파싱 (중첩 불릿 등 형식 변형 대응)
-    3. 휴리스틱 파싱 (최후 수단)
+    Three-stage fallback strategy:
+    1. Section parsing (the format the engine chain and rule-based fallback emit)
+    2. Lenient parsing (tolerates variants such as nested bullets)
+    3. Heuristic parsing (last resort)
 
-    예상 형식 (_build_ai_prompt / render_fallback_md가 지정하는 형식):
+    Expected format (as defined by _build_ai_prompt / render_fallback_md); headings in
+    any language are accepted because titles are taken verbatim:
     ## [1.2.3]
 
-    ### ✨ 기능
-    - 사용자 로그인 추가
-    - 대시보드 위젯 추가
+    ### ✨ Features
+    - Add user login
+    - Add dashboard widget
 
-    ### 🐛 수정
-    - 널 포인터 예외 수정
+    ### 🐛 Fixes
+    - Fix null pointer exception
     """
-    # 1단계: 섹션 파싱
+    # Stage 1: section parsing
     detected = _parse_markdown_sections(md_content)
     if detected:
-        print("  → 섹션 파서 성공")
+        print(t("changelog.parser_section_ok"))
         return detected
 
-    # 2단계: 관대한 파싱
+    # Stage 2: lenient parsing
     detected = _parse_markdown_lenient(md_content)
     if detected:
-        print("  → 관대한 파서 성공")
+        print(t("changelog.parser_lenient_ok"))
         return detected
 
-    # 3단계: 휴리스틱 파싱
+    # Stage 3: heuristic parsing
     detected = _parse_markdown_heuristic(md_content)
     if detected:
-        print("  → 휴리스틱 파서 성공")
+        print(t("changelog.parser_heuristic_ok"))
     return detected
 
 
-# `## [1.2.3]` / `## v1.2.3` 처럼 카테고리가 아니라 릴리즈 버전을 가리키는 헤더
+# Headings such as `## [1.2.3]` / `## v1.2.3` point at the release version, not a category
 _VERSION_HEADING_RE = re.compile(r'^\[?\s*v?\d+(?:\.\d+)*\s*\]?$')
 
 _HEADING_RE = re.compile(r'^\s{0,3}(#{2,6})\s+(.+?)\s*#*\s*$')
@@ -137,10 +195,10 @@ _BULLET_RE = re.compile(r'^\s*[\*\-\+]\s+(.+?)\s*$')
 
 def _parse_markdown_sections(md_content: str) -> dict:
     """
-    섹션 파서: `### 카테고리` 헤딩 + `- 항목` 불릿 형식.
+    Section parser: `### Category` heading + `- item` bullet format.
 
-    AI 엔진 체인(사용자 지정 API → Copilot CLI)과 규칙 기반 폴백이
-    동일하게 생성하는 형식이므로 1순위로 시도한다.
+    The engine chain (user API -> Copilot CLI) and the rule-based fallback emit
+    the same format, so it is tried first.
     """
     detected: dict[str, dict] = {}
     order: list[str] = []
@@ -150,11 +208,11 @@ def _parse_markdown_sections(md_content: str) -> dict:
         heading = _HEADING_RE.match(line)
         if heading:
             title = heading.group(2).strip()
-            # 버전 헤더(`## [1.2.3]`)는 카테고리가 아니다
+            # A version heading (`## [1.2.3]`) is not a category
             if not title or _VERSION_HEADING_RE.match(title):
                 current_key = None
                 continue
-            key = _make_safe_key(title, len(order))
+            key = _category_key(title, len(order))
             if key not in detected:
                 detected[key] = {'title': title, 'items': []}
                 order.append(key)
@@ -170,7 +228,7 @@ def _parse_markdown_sections(md_content: str) -> dict:
             if item:
                 detected[current_key]['items'].append(item)
 
-    # 헤딩만 있고 항목이 하나도 없으면 이 형식이 아니라고 보고 다음 파서로 넘긴다
+    # Headings without a single item mean this is not the format; hand over to the next parser
     if not any(entry['items'] for entry in detected.values()):
         return {}
 
@@ -179,50 +237,49 @@ def _parse_markdown_sections(md_content: str) -> dict:
 
 def _parse_markdown_lenient(md_content: str) -> dict:
     """
-    관대한 파서: 형식 변형에 대응.
+    Lenient parser: copes with format variants.
 
-    지원:
-    - 들여쓰기 1~8칸 (탭 포함)
-    - bold 선택적 (**제목** 또는 제목)
-    - 다양한 리스트 마커 (*, -, +)
+    Supports:
+    - 1-8 spaces of indentation (tabs included)
+    - optional bold (**Title** or Title)
+    - various list markers (*, -, +)
     """
     content = md_content.replace('\t', '    ')
     detected: dict[str, dict] = {}
 
-    # 패턴: 카테고리 + 중첩 항목
+    # Pattern: category + nested items
     pattern = r'(?:^|\n)([\*\-\+])\s*(\*\*)?([^\*\n]+?)(\*\*)?\s*\n((?:(?:^|\n)\s{1,8}[\*\-\+]\s+.+)*)'
     matches = re.findall(pattern, content, re.MULTILINE)
 
     for idx, (marker, bold_start, category_title, bold_end, items_text) in enumerate(matches):
         category_title = category_title.strip()
 
-        # 항목 추출
+        # Extract items
         items = re.findall(r'(?:^|\n)\s{1,8}[\*\-\+]\s+(.+)', items_text, re.MULTILINE)
         items = [item.strip() for item in items if item.strip()]
 
         if not category_title and not items:
             continue
 
-        # 너무 긴 제목은 카테고리가 아님
+        # A title that long is not a category
         if len(category_title) > 100:
             continue
 
-        safe_key = _make_safe_key(category_title, idx)
-        detected[safe_key] = {
-            'title': category_title,
-            'items': items,
-        }
+        safe_key = _category_key(category_title, idx)
+        # Same category twice (e.g. English and Korean titles) is merged, not overwritten
+        entry = detected.setdefault(safe_key, {'title': category_title, 'items': []})
+        entry['items'].extend(items)
 
     return detected
 
 
 def _parse_markdown_heuristic(md_content: str) -> dict:
     """
-    휴리스틱 파서: 줄 단위로 카테고리/항목 추론.
+    Heuristic parser: infer categories/items line by line.
 
-    규칙:
-    1. Bold 텍스트(**...**) → 카테고리
-    2. 들여쓰기 있는 줄 → 항목
+    Rules:
+    1. Bold text (**...**) -> category
+    2. Indented line -> item
     """
     lines = md_content.split('\n')
     detected: dict[str, dict] = {}
@@ -234,18 +291,18 @@ def _parse_markdown_heuristic(md_content: str) -> dict:
         if not stripped or stripped.startswith('<!--') or stripped.startswith('##'):
             continue
 
-        # Bold 텍스트 → 카테고리
+        # Bold text -> category
         bold_match = re.search(r'\*\*([^\*]+)\*\*', stripped)
         if bold_match:
             title = bold_match.group(1).strip()
             title = re.sub(r'^[\*\-\+\d\.]+\s*', '', title).strip()
 
             if title and len(title) < 100:
-                current_key = _make_safe_key(title, len(detected))
-                detected[current_key] = {'title': title, 'items': []}
+                current_key = _category_key(title, len(detected))
+                detected.setdefault(current_key, {'title': title, 'items': []})
             continue
 
-        # 들여쓰기 있는 줄 → 항목
+        # Indented line -> item
         if line.startswith((' ', '\t')) and stripped:
             item = re.sub(r'^[\*\-\+\d\.]+\s*', '', stripped).strip()
             item = re.sub(r'<[^>]+>', '', item).strip()
@@ -253,19 +310,19 @@ def _parse_markdown_heuristic(md_content: str) -> dict:
             if current_key and item and len(item) > 3:
                 detected[current_key]['items'].append(item)
 
-    # 빈 카테고리 제거
+    # Drop empty categories
     return {k: v for k, v in detected.items() if v.get('items')}
 
 
-# ------------------------ 3단계 규칙 기반 폴백 파서 ------------------------
+# ------------------------ 3-tier rule-based fallback parser ------------------------
 
-# 1단계 패턴은 제목도 같은 정규식에서 캡처한다 — " : type : " 마커(타입 앞 콜론에
-# 반드시 공백 선행)가 유일한 구분자이므로, 제목 안의 맨몸 콜론("v1:2" 등)에서
-# 잘리지 않는다. 별도 split 재수행 금지.
-# 타입은 대소문자를 가리지 않는다(Conventional Commits 스펙). `!`는 breaking 표시.
+# The tier-1 pattern captures the title in the same regex — the " : type : " marker
+# (the colon before the type must be preceded by a space) is the only separator, so a
+# bare colon inside the title ("v1:2" etc.) does not cut it short. Do not re-split.
+# Types are case-insensitive (per Conventional Commits). `!` marks a breaking change.
 _TIER1_RE = re.compile(r'^(.+?)\s:\s*(feat|fix|chore|docs|refactor|test)\s*(!)?\s*:\s*(.+)$', re.IGNORECASE)
 _TRAILING_URL_RE = re.compile(r'\s*https?://\S+$')
-# `feat : 내용`처럼 콜론 앞 공백도 흔한 표기라 허용한다.
+# A space before the colon, as in `feat : text`, is common, so it is allowed.
 _TIER2_RE = re.compile(
     r'^(feat|fix|chore|docs|refactor|test|perf|style|build|ci)(\([^)]*\))?\s*(!)?\s*:\s*(.+)$',
     re.IGNORECASE,
@@ -285,14 +342,16 @@ _TIER2_BUCKET_MAP = {
 
 _FALLBACK_BUCKET_KEYS = ('breaking', 'feat', 'fix', 'perf', 'chore', 'docs', 'refactor', 'test', 'deps', 'changes', 'wip')
 
-# 의존성 갱신(Dependabot·Renovate 등)과 작업 중 커밋은 일반 변경사항과 섞이면 노트가 흐려진다.
+# Dependency updates (Dependabot, Renovate, ...) and work-in-progress commits blur the notes when mixed with regular changes.
 _DEPS_SCOPE_RE = re.compile(r'^\(deps(?:-dev)?\)$', re.IGNORECASE)
 _DEPS_FREEFORM_RE = re.compile(r'^Bump \S+ from \S+ to \S+', re.IGNORECASE)
 _WIP_RE = re.compile(r'^\[?wip\b', re.IGNORECASE)
 
-# 승격 폭 판단 전용 — 표준 타입 뒤 `!` 마커와 본문 푸터 `BREAKING CHANGE:`가 breaking 신호.
-# `hotfix!:`·`WIP!:`처럼 표준 타입이 아닌 단어의 `!`는 되돌리기 어려운 major를 만들므로 인정하지 않는다.
-# 푸터는 커밋 목록에 본문 줄이 함께 들어올 때만 보인다(제목만 수집하면 `!` 마커만 판정된다).
+# Used only for the bump level — a `!` marker after a standard type and a body footer
+# `BREAKING CHANGE:` are the breaking signals.
+# A `!` after a non-standard word such as `hotfix!:` / `WIP!:` is not accepted, since it would
+# cause a hard-to-undo major bump.
+# The footer is only visible when body lines are part of the commit list (with subjects only, just the `!` marker counts).
 _BREAKING_FOOTER_RE = re.compile(r'^BREAKING[ -]CHANGE\s*:\s*(.*)$')
 
 
@@ -308,15 +367,15 @@ def _is_breaking(line: str) -> bool:
 
 def classify_commits(lines: list[str]) -> dict:
     """
-    커밋 제목 목록을 3단계 규칙으로 분류.
+    Classify commit subjects with a 3-tier rule set.
 
-    1단계: 제목 컨벤션 — "제목 : type : 내용 [URL]"
-    2단계: Conventional Commits — "type(scope)!: 내용"
-           (style/build/ci → chore, chore(deps)/build(deps) → deps 버킷)
-    3단계: 위 두 형식에 매칭되지 않으면 "changes" 버킷 (자유 형식, Bump… → deps, WIP → wip)
-    `!` 마커·BREAKING CHANGE 푸터는 "breaking" 버킷으로 모은다.
+    Tier 1: title convention — "title : type : text [URL]"
+    Tier 2: Conventional Commits — "type(scope)!: text"
+            (style/build/ci -> chore, chore(deps)/build(deps) -> deps bucket)
+    Tier 3: lines matching neither go to the "changes" bucket (free form, Bump... -> deps, WIP -> wip)
+    `!` markers and BREAKING CHANGE footers are collected in the "breaking" bucket.
 
-    제외 대상 (매칭 전에 걸러냄): [skip ci] 포함 줄, "Merge "로 시작하는 줄, 빈 줄.
+    Excluded (filtered before matching): lines containing [skip ci], lines starting with "Merge ", blank lines.
     """
     classified: dict[str, list[str]] = {key: [] for key in _FALLBACK_BUCKET_KEYS}
 
@@ -334,18 +393,19 @@ def classify_commits(lines: list[str]) -> dict:
                 classified['breaking'].append(footer.group(1).strip())
             continue
 
-        # 1단계가 2단계보다 먼저다 — 트레이드오프: "제목 : feat : 내용" 형식은
-        # "feat: ..." Conventional Commits와 겹칠 수 없지만(타입 앞에 제목 필수),
-        # 제목이 있는 줄에 " : type : "가 우연히 들어가면 tier-2 해석 기회 없이
-        # tier-1로 확정된다. 이 컨벤션을 쓰는 레포에서는 이것이 의도된 우선순위다.
+        # Tier 1 runs before tier 2 — trade-off: the "title : feat : text" format cannot
+        # overlap with "feat: ..." Conventional Commits (a title must precede the type),
+        # but a line with a title that happens to contain " : type : " is settled as
+        # tier 1 with no chance for tier-2 interpretation. For repos using this
+        # convention that is the intended priority.
         tier1 = _TIER1_RE.match(line)
         if tier1:
             title = tier1.group(1).strip()
             commit_type = tier1.group(2).lower()
             desc = tier1.group(4).strip()
-            # 커밋 말미의 이슈 URL은 릴리즈 노트 렌더링에서 노이즈 — 제거.
+            # A trailing issue URL on a commit is noise in the release notes — remove it.
             desc = _TRAILING_URL_RE.sub('', desc).strip()
-            # breaking 커밋은 major 승격의 근거라 별도 섹션에 드러낸다.
+            # A breaking commit justifies a major bump, so it gets its own section.
             bucket = 'breaking' if tier1.group(3) else commit_type
             classified[bucket].append(f"{title} — {desc}")
             continue
@@ -372,28 +432,24 @@ def classify_commits(lines: list[str]) -> dict:
     return classified
 
 
-_FALLBACK_SECTION_TITLES = {
-    'breaking': '### ⚠️ 호환성 깨짐',
-    'feat': '### ✨ 기능',
-    'fix': '### 🐛 수정',
-    'perf': '### ⚡ 성능',
-    'docs': '### 📝 문서',
-    'refactor': '### ♻️ 리팩토링',
-    'test': '### ✅ 테스트',
-    'deps': '### 📦 의존성',
-    'wip': '### 🚧 작업 중',
-}
+# Section titles come from the message catalog so they follow the configured language;
+# resolved lazily (not at import time) so the language can be switched per run.
+_FALLBACK_SECTION_KEYS = ('breaking', 'feat', 'fix', 'perf', 'docs', 'refactor', 'test', 'deps', 'changes', 'wip')
+
+
+def _section_title(bucket_key: str) -> str:
+    return t(f"changelog.section_{bucket_key}")
 
 
 def render_fallback_md(classified: dict, version: str) -> str:
-    """분류된 커밋 딕셔너리를 마크다운 릴리즈 노트로 렌더링."""
+    """Render the classified commit dict as Markdown release notes."""
     lines: list[str] = [f"## [{version}]", ""]
 
     def add_section(bucket_key):
         items = classified.get(bucket_key) or []
         if not items:
             return
-        lines.append(_FALLBACK_SECTION_TITLES[bucket_key])
+        lines.append(_section_title(bucket_key))
         for item in items:
             lines.append(f"- {item}")
         lines.append("")
@@ -405,7 +461,7 @@ def render_fallback_md(classified: dict, version: str) -> str:
     changes_items = list(classified.get('changes') or [])
     merged = chore_items + changes_items
     if merged:
-        lines.append("### 🔧 변경사항")
+        lines.append(_section_title('changes'))
         for item in merged:
             lines.append(f"- {item}")
         lines.append("")
@@ -416,11 +472,11 @@ def render_fallback_md(classified: dict, version: str) -> str:
 
 
 def classify_bump_level(lines: list[str]) -> str:
-    """커밋 제목 목록에서 semver 승격 폭을 규칙 기반으로 판단.
+    """Decide the semver bump level from commit subjects, rule-based.
 
-    - 표준 타입 뒤 `!` 마커 또는 `BREAKING CHANGE:` 푸터 포함 -> major
-    - `feat:`(classify_commits의 feat 버킷과 동일 판정 기준) 포함 -> minor
-    - 그 외(매칭 실패 포함) -> patch
+    - a `!` marker after a standard type, or a `BREAKING CHANGE:` footer -> major
+    - `feat:` (same criterion as the feat bucket of classify_commits) -> minor
+    - anything else (including no match) -> patch
     """
     for raw_line in lines:
         line = raw_line.strip()
@@ -432,22 +488,19 @@ def classify_bump_level(lines: list[str]) -> str:
     return 'minor' if classified.get('feat') else 'patch'
 
 
-_BUMP_AI_PROMPT_PREFIX = (
-    "다음은 정해진 커밋 컨벤션을 따르지 않는 자유형식 커밋 메시지들이다.\n"
-    "이 중 사용자 대상 새로운 기능(feature) 추가로 보이는 것이 하나라도 있으면 정확히 MINOR라고만 답하고,\n"
-    "없으면 정확히 PATCH라고만 답해라. 다른 말은 절대 덧붙이지 마라.\n"
-    "커밋 목록:\n"
-)
+def _bump_ai_prompt_prefix() -> str:
+    # The reply tokens MINOR/PATCH are parsed by code, so every language must ask for exactly those.
+    return t("changelog.bump_prompt_prefix")
 
 
 def _ai_assisted_minor_upgrade(unclassified_lines: list[str]) -> bool:
-    """규칙 분류가 patch일 때, 미분류 자유형식 커밋에 한해 AI에게 minor 업그레이드
-    여부만 보조 판단시킨다. AI는 절대 major를 만들 수 없다 — major는 항상 명시적
-    `!` 마커만 신뢰한다(classify_bump_level에서 이미 확정됨). 응답이 정확히
-    'MINOR'가 아니거나 호출이 실패하면 무조건 False(규칙 결과 patch 유지)."""
+    """When the rules say patch, ask the model only whether the unclassified free-form
+    commits justify a minor upgrade. The model can never produce a major — major only ever
+    trusts an explicit `!` marker (already settled in classify_bump_level). If the reply
+    is not exactly 'MINOR' or the call fails, always return False (keep the rule result, patch)."""
     if not unclassified_lines:
         return False
-    prompt = _BUMP_AI_PROMPT_PREFIX + "\n".join(f"- {line}" for line in unclassified_lines)
+    prompt = _bump_ai_prompt_prefix() + "\n".join(f"- {line}" for line in unclassified_lines)
 
     settings = _user_api_settings()
     if settings:
@@ -495,11 +548,11 @@ def cmd_collect_issue_closes(commit_shas_file: str, merged_prs_file: str) -> int
 
 
 def cmd_classify_bump(commits_file: str) -> int:
-    """커밋 목록 파일을 읽어 semver 승격 폭(major/minor/patch)을 stdout 마지막 줄에 출력.
+    """Read a commit list file and print the semver bump level (major/minor/patch) as the last stdout line.
 
-    규칙 우선(feat->minor, !마커->major, 그외->patch). 규칙 결과가 patch이고
-    분류 안 된 자유형식 커밋이 있으면, AI에게 patch->minor 업그레이드 여부만
-    보조 판단시킨다(major는 AI가 절대 만들 수 없음).
+    Rules first (feat->minor, ! marker->major, else patch). If the rule result is patch
+    and there are unclassified free-form commits, ask the model only whether to upgrade
+    patch->minor (the model can never produce a major).
     """
     try:
         with open(commits_file, 'r', encoding='utf-8') as f:
@@ -517,12 +570,12 @@ def cmd_classify_bump(commits_file: str) -> int:
     return 0
 
 
-# ------------------------ 서브커맨드 구현부 ------------------------
+# ------------------------ Subcommand implementations ------------------------
 
 def cmd_update_from_summary() -> int:
-    """pr_body.md에서 Markdown을 파싱하여 CHANGELOG.json 갱신."""
+    """Parse Markdown from pr_body.md and update CHANGELOG.json."""
     version = os.environ.get('VERSION')
-    # PROJECT_TYPES(csv)가 유일한 입력 — 단수 PROJECT_TYPE 폴백은 제거됐다
+    # PROJECT_TYPES (csv) is the only input — the singular PROJECT_TYPE fallback is gone
     project_types_csv = os.environ.get('PROJECT_TYPES', '')
     project_types = [t.strip() for t in project_types_csv.split(',') if t.strip()]
     today = os.environ.get('TODAY')
@@ -534,7 +587,7 @@ def cmd_update_from_summary() -> int:
     except ValueError:
         pr_number = None
 
-    # 입력 파일 찾기 (pr_body.md 우선, 폴백으로 summary_section.html)
+    # Find the input file (pr_body.md first, summary_section.html as fallback)
     input_file = None
     for filename in ['pr_body.md', 'summary_section.html']:
         if os.path.isfile(filename):
@@ -542,30 +595,30 @@ def cmd_update_from_summary() -> int:
             break
 
     if not input_file:
-        print("❌ 입력 파일을 찾을 수 없습니다 (pr_body.md 또는 summary_section.html)")
+        print(t("changelog.err_no_input"))
         return 1
 
     try:
         with open(input_file, 'r', encoding='utf-8') as f:
             content = f.read()
 
-        print(f"📄 입력 파일: {input_file}")
-        print(f"📝 파일 크기: {len(content)} bytes")
+        print(t("changelog.input_file", input_file=input_file))
+        print(t("changelog.file_size", size=len(content)))
 
-        # Markdown 파싱 (통합)
-        print("\n🔍 Markdown 파싱 시작...")
+        # Markdown parsing (unified)
+        print(t("changelog.parse_start"))
         categories = _parse_summary_markdown(content)
 
         parse_method = 'markdown' if categories else 'markdown_failed'
         if categories:
-            print(f"✅ 파싱 성공: {len(categories)}개 카테고리")
+            print(tn("changelog.parse_ok", len(categories)))
         else:
-            print("⚠️ 파싱 실패, raw_summary만 저장")
+            print(t("changelog.parse_failed"))
 
-        # raw_summary 생성 (노이즈 제거)
+        # Build raw_summary (noise removed)
         raw_summary = _strip_version_headings(_clean_summary_noise(content))
 
-        # 릴리즈 데이터 생성
+        # Build the release record
         new_release = {
             "version": version,
             "project_types": project_types,
@@ -576,24 +629,24 @@ def cmd_update_from_summary() -> int:
             "parse_method": parse_method,
         }
 
-        # 파싱 결과 출력
-        print("\n📊 파싱 결과:")
-        print(f"  - 파싱 방식: {parse_method}")
-        print(f"  - raw_summary 길이: {len(raw_summary)} 문자")
-        print(f"  - 파싱된 카테고리: {len(categories)}개")
+        # Print the parse result
+        print(t("changelog.result_header"))
+        print(t("changelog.result_method", method=parse_method))
+        print(t("changelog.result_raw_len", n=len(raw_summary)))
+        print(t("changelog.result_categories", n=len(categories)))
         for key, value in categories.items():
             title = value.get('title', key)
             items_count = len(value.get('items', []))
-            print(f"    • {title}: {items_count}개 항목")
+            print(tn("changelog.result_category_item", items_count, title=title))
 
-        # CHANGELOG.json 업데이트
+        # Update CHANGELOG.json
         try:
             with open('CHANGELOG.json', 'r', encoding='utf-8') as f:
                 changelog_data = json.load(f)
         except json.JSONDecodeError as e:
-            # 머지 충돌 마커 등으로 깨진 파일을 새 구조로 덮으면 기존 이력이 전부 사라진다.
-            print(f"❌ CHANGELOG.json을 해석할 수 없어 갱신을 중단합니다 (기존 이력 보호): {e}")
-            print(f"::error::CHANGELOG.json이 올바른 JSON이 아닙니다: {e}", file=sys.stderr)
+            # Overwriting a file broken by e.g. merge-conflict markers with a fresh structure would erase all history.
+            print(t("changelog.err_json_unreadable", error=e))
+            print(t("changelog.err_json_annotation", error=e), file=sys.stderr)
             return 1
         except FileNotFoundError:
             changelog_data = {
@@ -606,8 +659,8 @@ def cmd_update_from_summary() -> int:
                 "releases": [],
             }
 
-        # 방어: 파일이 존재하지만 스캐폴드 등 비정형 구조({"versions": []})라
-        # metadata/releases 키가 없을 수 있다 — 릴리스를 절대 막지 않는다 (실측: dogfood PR #1)
+        # Defensive: the file may exist in an irregular scaffold structure ({"versions": []})
+        # without metadata/releases keys — never block a release because of it
         if not isinstance(changelog_data, dict):
             changelog_data = {}
         changelog_data.setdefault("metadata", {})
@@ -615,7 +668,7 @@ def cmd_update_from_summary() -> int:
         changelog_data["metadata"]["lastUpdated"] = timestamp
         changelog_data["metadata"]["currentVersion"] = version
         changelog_data["metadata"]["projectTypes"] = project_types
-        # 같은 버전은 교체한다 — 워크플로우 재실행 시 항목이 중복으로 쌓이지 않게.
+        # Replace the same version — so re-running the workflow does not pile up duplicates.
         releases = [
             r for r in (changelog_data.get("releases") or [])
             if not (isinstance(r, dict) and str(r.get("version")) == str(version))
@@ -627,17 +680,17 @@ def cmd_update_from_summary() -> int:
         with open('CHANGELOG.json', 'w', encoding='utf-8') as f:
             json.dump(changelog_data, f, indent=2, ensure_ascii=False)
 
-        print("\n✅ CHANGELOG.json 업데이트 완료!")
+        print(t("changelog.json_updated"))
         return 0
 
     except Exception as e:
-        print(f"❌ update-from-summary 실패: {e}")
+        print(t("changelog.err_update_failed", error=e))
         traceback.print_exc()
         return 1
 
 
 def cmd_generate_md() -> int:
-    """CHANGELOG.json을 기반으로 CHANGELOG.md 재생성."""
+    """Regenerate CHANGELOG.md from CHANGELOG.json."""
     try:
         with open('CHANGELOG.json', 'r', encoding='utf-8') as f:
             data = json.load(f)
@@ -649,8 +702,8 @@ def cmd_generate_md() -> int:
             current_version = metadata.get('currentVersion', 'Unknown')
             last_updated = metadata.get('lastUpdated', 'Unknown')
 
-            f.write(f"**현재 버전:** {current_version}  \n")
-            f.write(f"**마지막 업데이트:** {last_updated}  \n\n")
+            f.write(t("changelog.md_current_version", version=current_version) + "  \n")
+            f.write(t("changelog.md_last_updated", updated=last_updated) + "  \n\n")
             f.write("---\n\n")
 
             for release in data.get('releases', []):
@@ -663,52 +716,43 @@ def cmd_generate_md() -> int:
                 if pr_number is not None:
                     f.write(f"**PR:** #{pr_number}  \n\n")
 
-                parsed = release.get('parsed_changes') or {}
+                parsed = _normalize_parsed_changes(release.get('parsed_changes'))
 
                 if parsed:
-                    # 구조화된 데이터 출력
-                    for _, items in parsed.items():
-                        if not items:
-                            continue
-                        if isinstance(items, dict) and 'items' in items:
-                            actual_items = items.get('items') or []
-                            title = items.get('title') or ''
-                        else:
-                            actual_items = items
-                            title = _normalize_text(_)
-
-                        f.write(f"**{title}**\n")
-                        for item in actual_items:
+                    # Print the structured data; headings follow the current language
+                    for key, entry in parsed.items():
+                        f.write(f"**{_category_display_title(key, entry['title'])}**\n")
+                        for item in entry['items']:
                             f.write(f"- {item}\n")
                         f.write("\n")
                 else:
-                    # 파싱 실패 시 raw_summary 출력
+                    # On parse failure, print raw_summary
                     raw_summary = release.get('raw_summary', '').strip()
                     if raw_summary:
                         raw_summary = _strip_version_headings(_clean_summary_noise(raw_summary))
                         if raw_summary:
                             f.write(raw_summary + "\n\n")
                         else:
-                            f.write("*변경사항 정보 없음*\n\n")
+                            f.write(t("changelog.md_no_changes") + "\n\n")
                     else:
-                        f.write("*변경사항 정보 없음*\n\n")
+                        f.write(t("changelog.md_no_changes") + "\n\n")
 
                 f.write("---\n\n")
 
-        print("✅ CHANGELOG.md 재생성 완료!")
+        print(t("changelog.md_regenerated"))
         return 0
 
     except Exception as e:
-        print(f"❌ CHANGELOG.md 생성 실패: {e}")
+        print(t("changelog.err_md_failed", error=e))
         traceback.print_exc()
         return 1
 
 
 def cmd_export_release_notes(version: str, output_path: str | None) -> int:
-    """CHANGELOG에서 해당 버전 릴리즈 노트를 생성."""
+    """Build the release notes of the given version from the CHANGELOG."""
     notes_text = ""
 
-    # 1) CHANGELOG.json 시도
+    # 1) Try CHANGELOG.json
     try:
         if os.path.isfile('CHANGELOG.json'):
             with open('CHANGELOG.json', 'r', encoding='utf-8') as f:
@@ -716,24 +760,23 @@ def cmd_export_release_notes(version: str, output_path: str | None) -> int:
             releases = changelog.get('releases') or []
             matched = next((r for r in releases if str(r.get('version')) == str(version)), None)
             if matched:
-                header = f"버전 {matched.get('version')} 업데이트\n\n"
-                parsed_changes = matched.get('parsed_changes') or {}
+                header = t("changelog.export_header", version=matched.get('version')) + "\n\n"
+                parsed_changes = _normalize_parsed_changes(matched.get('parsed_changes'))
                 if parsed_changes:
                     category_blocks: list[str] = []
-                    for _, value in parsed_changes.items():
-                        title = (value.get('title') or '').strip()
-                        items = [it for it in (value.get('items') or []) if it]
-                        if title and items:
-                            block = "**" + title + "**\n" + "\n".join("- " + it for it in items)
+                    for key, entry in parsed_changes.items():
+                        title = _category_display_title(key, entry['title']).strip()
+                        if title and entry['items']:
+                            block = "**" + title + "**\n" + "\n".join("- " + it for it in entry['items'])
                             category_blocks.append(block)
                     body = "\n\n".join(category_blocks) if category_blocks else _strip_version_headings((matched.get('raw_summary') or '').strip())
                 else:
                     body = _strip_version_headings((matched.get('raw_summary') or '').strip())
                 notes_text = (header + (body or "")).strip()
     except Exception as e:
-        print(f"::warning::CHANGELOG.json에서 {version} 노트를 읽지 못했습니다: {e}", file=sys.stderr)
+        print(t("changelog.warn_json_notes", version=version, error=e), file=sys.stderr)
 
-    # 2) CHANGELOG.md 폴백
+    # 2) CHANGELOG.md fallback
     if not notes_text and os.path.isfile('CHANGELOG.md'):
         try:
             with open('CHANGELOG.md', 'r', encoding='utf-8') as f:
@@ -744,16 +787,16 @@ def cmd_export_release_notes(version: str, output_path: str | None) -> int:
                 start = m.end()
                 next_m = re.search(r"^## \[", md[start:], re.MULTILINE)
                 section = md[start: start + next_m.start()] if next_m else md[start:]
-                # generate-md가 릴리스 사이에 넣는 구분선은 노트 내용이 아니다
+                # The separator generate-md puts between releases is not note content
                 body = re.sub(r'(?:\n\s*-{3,}\s*)+$', '', '\n' + section.strip()).strip()
-                notes_text = (f"버전 {version} 업데이트\n\n" + body).strip()
+                notes_text = (t("changelog.export_header", version=version) + "\n\n" + body).strip()
         except Exception as e:
-            # 조용히 삼키면 고정 문구 폴백이 정상 출력처럼 보여 원인을 알 수 없다.
-            print(f"::warning::CHANGELOG.md에서 {version} 노트를 읽지 못했습니다: {e}", file=sys.stderr)
+            # Swallowing it silently would make the fixed-text fallback look like normal output with no visible cause.
+            print(t("changelog.warn_md_notes", version=version, error=e), file=sys.stderr)
 
-    # 3) 최종 폴백
+    # 3) Final fallback
     if not notes_text:
-        notes_text = f"버전 {version} 업데이트\n앱 안정성 및 사용자 경험이 개선되었습니다."
+        notes_text = t("changelog.export_fallback", version=version)
 
     if output_path:
         with open(output_path, 'w', encoding='utf-8') as f:
@@ -763,17 +806,17 @@ def cmd_export_release_notes(version: str, output_path: str | None) -> int:
     return 0
 
 
-# ------------------------ ai-summary 엔진 체인 ------------------------
+# ------------------------ ai-summary engine chain ------------------------
 
-# Copilot Free/Student 계정은 모델명 지정이 거부되고 auto 모델 선택만 허용된다.
+# Copilot Free/Student accounts reject an explicit model name and only allow auto model selection.
 _COPILOT_MODEL = "auto"
 _COPILOT_TIMEOUT_SECONDS = 90
 
 
 def _warn_engine_failure(message: str) -> str:
-    """엔진 실패를 Actions 실행 요약(Annotations)에 경고로 띄운다.
-    평문 로그만 남기면 잡 로그를 열기 전에는 fallback 사유를 알 수 없다.
-    stdout은 결과 JSON 계약용이라 stderr로 쓴다. 반환값은 한 줄로 줄인 사유."""
+    """Surface an engine failure as a warning in the Actions run summary (Annotations).
+    With plain logs only, the fallback reason stays hidden until the job log is opened.
+    stdout is reserved for the result JSON contract, so this writes to stderr. Returns the reason squeezed onto one line."""
     reason = " ".join(str(message).split())[:200]
     escaped = reason.replace('%', '%25').replace('\r', '%0D').replace('\n', '%0A')
     print(f"::warning::{escaped}", file=sys.stderr)
@@ -781,42 +824,36 @@ def _warn_engine_failure(message: str) -> str:
 
 
 def _user_api_settings() -> tuple[str, str, str] | None:
-    """사용자 지정 AI 티어 설정. AI_API_KEY와 AI_API_BASE_URL, AI_MODEL이 모두 있어야 한다.
+    """Settings for the user-supplied model tier. AI_API_KEY, AI_API_BASE_URL and AI_MODEL must all be present.
 
-    키만 있고 URL·모델이 비어 있으면 그 키를 어디로도 보내지 않고 경고 후 건너뛴다
-    (종료된 기본 엔드포인트으로 사용자 키가 흘러가던 문제 방지)."""
+    If only the key is set and URL/model are empty, the key is sent nowhere: warn and skip
+    (prevents the user's key from flowing to a retired default endpoint)."""
     api_key = os.environ.get('AI_API_KEY')
     base_url = os.environ.get('AI_API_BASE_URL')
     model = os.environ.get('AI_MODEL')
     if not api_key:
-        # 변수만 등록하고 secret을 빠뜨리면 아무 표시 없이 규칙 요약으로 넘어가 설정이 먹은 줄 안다
+        # If only the variables are registered and the secret is missing, it falls to the rule summary unnoticed and the user thinks the setup worked
         if base_url or model:
-            print(
-                "::warning::AI_API_BASE_URL/AI_MODEL이 설정됐지만 AI_API_KEY secret이 없어 사용자 API 티어를 건너뜁니다",
-                file=sys.stderr,
-            )
+            print(t("changelog.warn_missing_key"), file=sys.stderr)
         return None
     if not base_url or not model:
-        print(
-            "::warning::AI_API_KEY가 설정됐지만 AI_API_BASE_URL/AI_MODEL이 없어 사용자 API 티어를 건너뜁니다",
-            file=sys.stderr,
-        )
+        print(t("changelog.warn_missing_url_model"), file=sys.stderr)
         return None
     return api_key, base_url, model
 
 
 def _copilot_enabled() -> bool:
-    """version.yml의 copilot_ai가 켜져 있고(워크플로우가 COPILOT_AI로 전달) 토큰이 있을 때만 True."""
+    """True only when copilot_ai is on in version.yml (passed by the workflow as COPILOT_AI) and a token is present."""
     return os.environ.get('COPILOT_AI', '').strip().lower() == 'true' and bool(os.environ.get('GITHUB_TOKEN'))
 
 
 def call_copilot_cli(prompt: str) -> str:
-    """Copilot CLI를 텍스트 생성 전용으로 호출해 응답 텍스트를 반환.
+    """Call the Copilot CLI for text generation only and return the response text.
 
-    프롬프트에 필요한 정보가 이미 다 들어 있으므로 에이전트 기능은 전부 막는다:
-    빈 임시 디렉터리에서 실행하고, shell/write/url 도구를 거부하며, 내장 MCP와
-    커스텀 지침 로딩을 끈다.
-    실패(비정상 종료·타임아웃·CLI 없음)는 예외로 올려 호출부가 fallback한다."""
+    The prompt already carries all needed information, so every tool capability is blocked:
+    run in an empty temp directory, deny the shell/write/url tools, and turn off the
+    built-in MCPs and custom-instruction loading.
+    Failures (non-zero exit, timeout, missing CLI) are raised so the caller falls back."""
     with tempfile.TemporaryDirectory() as workdir:
         result = subprocess.run(
             [
@@ -834,10 +871,10 @@ def call_copilot_cli(prompt: str) -> str:
 
 
 def _is_valid_copilot_summary(text: str) -> bool:
-    """프롬프트가 요구한 Markdown 형식인지 최소한만 검사한다.
+    """Minimal check that the text is the Markdown format the prompt asked for.
 
-    섹션 헤딩('### ')이 하나도 없거나 코드펜스로 시작하는(통째로 감싼) 응답은 릴리스 노트로
-    쓰지 않는다."""
+    A response with no section heading ('### ') at all, or one starting with a code fence
+    (wrapped as a whole), is not used as release notes."""
     stripped = text.strip()
     if not stripped or stripped.startswith('```'):
         return False
@@ -845,33 +882,34 @@ def _is_valid_copilot_summary(text: str) -> bool:
 
 
 def _build_ai_prompt(commit_lines: list[str], pr_title: str | None, version: str, diff_stat: str | None = None) -> str:
-    """AI에게 보낼 한국어 릴리즈 요약 프롬프트를 구성.
+    """Build the release-summary prompt sent to the model (in the configured language).
 
-    요청하는 출력 형식은 규칙 기반 폴백 렌더러(render_fallback_md)와 동일한
-    형식으로 맞춘다 — 다운스트림(릴리즈 노트 소비자)이 엔진과 무관하게 단일
-    형식만 보게 하기 위함이다.
+    The requested output format matches the rule-based fallback renderer
+    (render_fallback_md) — so downstream consumers of the release notes see a single
+    format regardless of the engine.
     """
+    titles = {key: _section_title(key) for key in _FALLBACK_SECTION_KEYS}
     parts = [
-        "아래 커밋 목록을 바탕으로 한국어 릴리즈 요약을 작성해줘.",
-        f"출력 형식: 첫 줄은 '## [{version}]' 헤더로 시작하고,",
-        "해당 항목이 있는 섹션만 다음 이름으로 작성해줘:",
-        "'### ⚠️ 호환성 깨짐', '### ✨ 기능', '### 🐛 수정', '### ⚡ 성능', '### 📝 문서', '### ♻️ 리팩토링',",
-        "'### ✅ 테스트', '### 📦 의존성', '### 🔧 변경사항', '### 🚧 작업 중'.",
-        "타입 뒤에 '!'가 붙었거나 BREAKING CHANGE인 커밋은 반드시 '### ⚠️ 호환성 깨짐'에 넣어줘.",
-        "각 항목은 '- '로 시작하는 불릿으로 작성해줘.",
+        t("changelog.prompt_intro"),
+        t("changelog.prompt_format", version=version),
+        t("changelog.prompt_sections_intro"),
+        t("changelog.prompt_names_1", **titles),
+        t("changelog.prompt_names_2", **titles),
+        t("changelog.prompt_breaking", **titles),
+        t("changelog.prompt_bullets"),
     ]
     if pr_title:
-        parts.append(f"PR 제목: {pr_title}")
+        parts.append(t("changelog.prompt_pr_title", title=pr_title))
     if diff_stat and diff_stat.strip():
-        parts.append("파일별 변경 요약:")
+        parts.append(t("changelog.prompt_diff_stat"))
         parts.append(diff_stat.strip())
-    parts.append("커밋 목록:")
+    parts.append(t("changelog.prompt_commits"))
     parts.extend(f"- {line}" for line in commit_lines)
     return "\n".join(parts)
 
 
 def call_openai_compatible(base_url: str, token: str, model: str, prompt: str) -> str:
-    """OpenAI 호환 /chat/completions 엔드포인트 호출 후 응답 텍스트 반환."""
+    """Call an OpenAI-compatible /chat/completions endpoint and return the response text."""
     url = base_url.rstrip('/') + "/chat/completions"
     payload = {
         "model": model,
@@ -893,12 +931,12 @@ def call_openai_compatible(base_url: str, token: str, model: str, prompt: str) -
 
 
 def cmd_ai_summary(commits_file: str, version: str, output_path: str, pr_title: str | None, diff_stat_file: str | None = None) -> int:
-    """커밋 목록을 읽어 AI(우선) 또는 규칙 기반 폴백으로 릴리즈 요약을 생성."""
+    """Read the commit list and build a release summary with the model (preferred) or the rule-based fallback."""
     try:
         with open(commits_file, 'r', encoding='utf-8') as f:
             commit_lines = [line.rstrip('\n').rstrip('\r') for line in f]
     except Exception as e:
-        print(f"::warning::커밋 목록 파일을 읽지 못해 빈 목록으로 요약합니다: {e}", file=sys.stderr)
+        print(t("changelog.warn_commits_unreadable", error=e), file=sys.stderr)
         commit_lines = []
 
     diff_stat = None
@@ -948,16 +986,16 @@ def cmd_ai_summary(commits_file: str, version: str, output_path: str, pr_title:
         with open(output_path, 'w', encoding='utf-8') as f:
             f.write(summary_text)
     except Exception as e:
-        # 파일을 못 쓴 사실을 숨기지 않는다 — ok=false로 보고하고,
-        # 요약 텍스트는 stderr로 구제 출력한다. 종료 코드는 0 유지
-        # (워크플로우 파이프라인을 끊지 않기 위한 계약).
+        # Do not hide that the file could not be written — report ok=false and
+        # rescue-print the summary text to stderr. Keep exit code 0
+        # (contract so the workflow pipeline is not cut).
         write_ok = False
         print(f"[warn] output write failed: {e}", file=sys.stderr)
         print(summary_text, file=sys.stderr)
 
     result = {"ok": write_ok, "engine": engine, "output": output_path}
     if engine == "fallback" and failures:
-        # 워크플로우가 PR 댓글의 engine 줄에 사유를 붙일 수 있도록 함께 넘긴다.
+        # Passed along so the workflow can append the reason to the engine line of the PR comment.
         result["fallback_reason"] = "; ".join(r.replace("[warn] ", "", 1) for r in failures)
     print(json.dumps(result))
     return 0
@@ -966,33 +1004,34 @@ def cmd_ai_summary(commits_file: str, version: str, output_path: str, pr_title:
 # ------------------------------- CLI -------------------------------
 
 def main(argv: list[str] | None = None) -> int:
+    use_utf8_output()
     parser = argparse.ArgumentParser(
         prog='changelog_manager',
-        description='통합 체인지로그 매니저',
+        description=t('changelog.cli_description'),
         add_help=True
     )
     sub = parser.add_subparsers(dest='command', required=True)
 
-    sub.add_parser('update-from-summary', help='PR body에서 CHANGELOG.json 갱신')
-    sub.add_parser('generate-md', help='CHANGELOG.json → CHANGELOG.md 생성')
+    sub.add_parser('update-from-summary', help=t('changelog.cli_update_help'))
+    sub.add_parser('generate-md', help=t('changelog.cli_generate_help'))
 
-    p_classify_bump = sub.add_parser('classify-bump', help='커밋 목록으로 semver 승격 폭(major/minor/patch) 판단')
-    p_classify_bump.add_argument('--commits-file', required=True, help='커밋 제목 목록 파일 (한 줄당 1개)')
+    p_classify_bump = sub.add_parser('classify-bump', help=t('changelog.cli_classify_help'))
+    p_classify_bump.add_argument('--commits-file', required=True, help=t('changelog.cli_commits_file_help'))
 
-    p_export = sub.add_parser('export', help='특정 버전 릴리즈 노트 추출')
-    p_export.add_argument('--version', required=True, help='버전 번호')
-    p_export.add_argument('--output', help='출력 파일 경로 (없으면 stdout)')
+    p_export = sub.add_parser('export', help=t('changelog.cli_export_help'))
+    p_export.add_argument('--version', required=True, help=t('changelog.cli_version_help'))
+    p_export.add_argument('--output', help=t('changelog.cli_output_help'))
 
-    p_ai_summary = sub.add_parser('ai-summary', help='커밋 목록으로 AI/규칙 기반 릴리즈 요약 생성')
-    p_ai_summary.add_argument('--commits-file', required=True, help='커밋 제목 목록 파일 (한 줄당 1개)')
-    p_ai_summary.add_argument('--version', required=True, help='버전 번호')
-    p_ai_summary.add_argument('--output', required=True, help='요약 결과를 저장할 파일 경로')
-    p_ai_summary.add_argument('--pr-title', help='PR 제목 (프롬프트 컨텍스트로 사용, 선택)')
-    p_ai_summary.add_argument('--diff-stat-file', help='git diff --stat 출력 파일 (프롬프트 컨텍스트 확장, 선택)')
+    p_ai_summary = sub.add_parser('ai-summary', help=t('changelog.cli_ai_summary_help'))
+    p_ai_summary.add_argument('--commits-file', required=True, help=t('changelog.cli_commits_file_help'))
+    p_ai_summary.add_argument('--version', required=True, help=t('changelog.cli_version_help'))
+    p_ai_summary.add_argument('--output', required=True, help=t('changelog.cli_summary_output_help'))
+    p_ai_summary.add_argument('--pr-title', help=t('changelog.cli_pr_title_help'))
+    p_ai_summary.add_argument('--diff-stat-file', help=t('changelog.cli_diff_stat_help'))
 
-    p_collect = sub.add_parser('collect-issue-closes', help='develop에 머지된 PR 중 이번 릴리스에 포함된 이슈 번호 목록 추출')
-    p_collect.add_argument('--commit-shas-file', required=True, help='이번 릴리스에 포함된 커밋 SHA 목록 파일 (한 줄당 1개)')
-    p_collect.add_argument('--merged-prs-file', required=True, help='gh pr list --json number,headRefName,mergeCommit 출력 JSON 파일')
+    p_collect = sub.add_parser('collect-issue-closes', help=t('changelog.cli_collect_help'))
+    p_collect.add_argument('--commit-shas-file', required=True, help=t('changelog.cli_shas_help'))
+    p_collect.add_argument('--merged-prs-file', required=True, help=t('changelog.cli_prs_help'))
 
     args = parser.parse_args(argv)