Class LocaleRegistry

현재 활성 로케일 id. / Current active locale id.

그리드 생성 시 options.messages 로 넘긴 문구를 인스턴스 오버라이드에 기록한다(내부 배선용; 여러 문구를 한 번에 넣고 싶을 때 직접 호출해도 된다). / Records the messages passed via options.messages at grid construction into instance overrides (internal wiring; can also be called directly to set several overrides at once).

한 페이지에 그리드가 여러 개 있을 때, 그리드마다 다른 문구를 쓰고 싶으면 이 자식 레지스트리로 전역 카탈로그는 그대로 두고 인스턴스 하나만 격리해 오버라이드한다. / When a page hosts multiple grids that each need different wording, use this child registry to isolate overrides to one instance while the global catalog stays untouched.

기존 로케일 위에 일부 키만 겹쳐 쓴다(2단 딥머지). 예: en 카탈로그는 그대로 두고 버튼 문구 하나만 다른 톤으로 바꾸고 싶을 때, 로케일 전체를 다시 등록할 필요 없이 이 메서드로 충분하다. 미존재 id 면 새로 생성하고, 원본(ko 등)은 건드리지 않는다. / Overlay a few keys onto an existing locale (2-level deep-merge). e.g. keep the en catalog as-is and just re-word one button label — no need to re-register the whole locale. Creates the id if it doesn't exist yet; the base locale (ko, …) is left untouched.

로케일 원본(자기 계층). 병합·부모체인 해석 뷰가 아님. / Raw locale (own layer) — not a merged/chain-resolved view.

로케일(자기 계층)이 등록돼 있는가. / Whether the locale is registered (own layer).

등록된 로케일 id 목록(부모체인 합집합). / Registered locale ids (union across the parent chain).

활성 로케일 meta(폴백 병합 후). ExportManager 등 포맷 소비자용. / Active-locale meta (after fallback merge). For format consumers (e.g. ExportManager).

새 언어 카탈로그를 통째로(또는 일부만) 등록한다. 예: 프랑스어 지원을 추가할 때 전체 키를 다 채우지 못했더라도 일단 등록해 두면, 미채운 키는 기본 로케일 ko 로 자동 대체된다 (never-throw 폴백, t() 참고). 반환하는 { missingKeys } 는 ko(단일 진실 공급원) 대비 빠진 키 목록으로, 등록을 막지 않고 누락만 알리는 신호다 — 번역 진행률 체크에 쓴다. / Register a whole (or partial) locale catalog. e.g. when adding French support, you can register an incomplete catalog and missing keys silently fall back to the base locale ko (never-throw, see t()). The returned { missingKeys } lists keys still missing versus ko (the single source of truth) — a non-blocking signal you can use to track translation progress.

사용자가 화면에서 언어 설정을 바꿨을 때 호출해 활성 로케일을 전환한다. 렌더 루프 도중 불려도 안전하도록, 미등록 id 는 throw 하지 않고 console.warn 후 현재 로케일을 유지한다 (never-throw). / Call when the user switches their language setting to change the active locale. Safe to call mid-render: unknown ids warn (never throw) and keep the current locale.

로케일과 무관하게 이 인스턴스에서만 문구 하나를 즉시 바꾼다(최우선 순위). 언어를 en 으로 바꿔도 이 오버라이드는 유지된다 — "이 그리드에서만 이 라벨을 이렇게 부르고 싶다"는 요구에 쓴다. / Overrides a single message for this instance only, regardless of the active locale (highest priority). Switching to en keeps the override — use it for "just this grid should call this label X".

키로 문구를 찾아 반환한다. 렌더 루프(매 프레임 호출될 수 있는 자리)에서 쓰는 소비자용 API라 절대 throw 하지 않는다 — 순서대로 (1) 이 인스턴스의 오버라이드 → (2) 활성 로케일 → (3) extends 로 지정한 상속 로케일 → (4) 기본 로케일 ko 를 찾고, 그래도 없으면 키 문자열 자체를 돌려주며 콘솔에 경고를 1회만 남긴다("화면에 아무것도 안 뜨는 것"보다 "키 그대로 보이는 것"이 디버깅에 낫다). params 를 주면 {name} 형태의 자리표시자를 채운다. / Look up a message by key and return it. Because this is the consumer-facing API called from the render loop (potentially every frame), it never throws — it walks (1) this instance's overrides → (2) the active locale → (3) the locale named in extends → (4) the base locale ko, and if still unresolved, returns the key string itself with a single console warning (a raw key beats rendering nothing, for debugging). Pass params to fill {name}-style placeholders.