Class LocaleRegistry

현재 활성 로케일 id.

Current active locale id.

現在のアクティブロケール id。

当前活动区域设置 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).

グリッド生成時に options.messages で渡した文言をインスタンスのオーバーライドに記録します (内部配線用; 複数の文言を一度に入れたいときは直接呼び出しても構いません)。

把表格创建时通过 options.messages 传入的文案记录到实例覆盖中(内部接线用；想一次放入 多条文案时也可以直接调用)。

한 페이지에 그리드가 여러 개 있을 때, 그리드마다 다른 문구를 쓰고 싶으면 이 자식 레지스트리로 전역 카탈로그는 그대로 두고 인스턴스 하나만 격리해 오버라이드한다.

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.

1ページにグリッドが複数あるとき、グリッドごとに違う文言を使いたければ、この子レジストリで グローバルカタログはそのままにして、インスタンス一つだけを隔離してオーバーライドします。

一个页面上有多个表格、想让每个表格用不同文案时，用这个子注册表保持全局目录不变， 只隔离一个实例来覆盖。

기존 로케일 위에 일부 키만 겹쳐 쓴다(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.

既存のロケールの上に一部のキーだけを重ねて書きます(2段ディープマージ)。例: en カタログは そのままにして、ボタンの文言一つだけを違うトーンに変えたいとき、ロケール全体を登録し直す 必要はなく、このメソッドで十分です。存在しない id なら新規に作成し、元(ko など)には 手を触れません。

在已有区域设置之上只覆盖一部分键(2 段深合并)。例: 想保持 en 目录不变，只把一个按钮文案 换成别的语气时，无需重新注册整个区域设置，用本方法就够了。id 不存在则新建，原本(ko 等) 不受影响。

로케일 원본(자기 계층). 병합·부모체인 해석 뷰가 아님.

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).

登録済みロケール id の一覧(親チェーンの和集合)。

已注册的区域设置 id 的列表(父链的并集)。

활성 로케일 meta(폴백 병합 후). ExportManager 등 포맷 소비자용.

Active-locale meta (after fallback merge). For format consumers (e.g. ExportManager).

アクティブロケールの meta(フォールバックのマージ後)。ExportManager などフォーマット消費者向け。

活动区域设置的 meta(回退合并之后)。供 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.

新しい言語カタログを丸ごと(または一部だけ)登録します。例: フランス語対応を追加するとき、 全キーを埋めきれていなくてもひとまず登録しておけば、埋めていないキーは既定ロケール ko に 自動で差し替わります(never-throw フォールバック、t() を参照)。返却する { missingKeys } は ko(信頼できる唯一の情報源)に対して欠けているキーの一覧で、登録を妨げずに漏れだけを知らせる シグナルです — 翻訳の進捗チェックに使います。

注册整份(或部分)语言目录。例: 添加法语支持时，即使没有填完全部键也可以先注册，未填的键会 自动回退到默认区域设置 ko(never-throw 回退，参见 t())。返回的 { missingKeys } 是相对 ko(唯一可信信息源)仍缺失的键的列表，是一个不阻断注册、只提示遗漏的信号 — 用于检查翻译进度。

사용자가 화면에서 언어 설정을 바꿨을 때 호출해 활성 로케일을 전환한다. 렌더 루프 도중 불려도 안전하도록, 미등록 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.

ユーザーが画面で言語設定を変えたときに呼び出して、アクティブロケールを切り替えます。 レンダーループの途中で呼ばれても安全なように、未登録の id は throw せず console.warn した うえで現在のロケールを維持します(never-throw)。

用户在界面上改变语言设置时调用，用于切换活动区域设置。为了在渲染循环中途被调用也安全， 未注册的 id 不会 throw，而是 console.warn 之后保持当前区域设置(never-throw)。

로케일과 무관하게 이 인스턴스에서만 문구 하나를 즉시 바꾼다(최우선 순위). 언어를 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".

ロケールとは無関係に、このインスタンスでだけ文言一つを即座に変えます(最優先)。言語を en に 変えてもこのオーバーライドは維持されます — 「このグリッドでだけこのラベルをこう呼びたい」と いう要求に使います。

与区域设置无关，只在本实例上立即改变一条文案(优先级最高)。语言换成 en 后这个覆盖依然保留 — 用于「只在这个表格里把这个标签这样叫」的需求。

키로 문구를 찾아 반환한다. 렌더 루프(매 프레임 호출될 수 있는 자리)에서 쓰는 소비자용 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.

キーで文言を探して返します。レンダーループ(毎フレーム呼ばれうる場所)で使う消費者向けの API なので、絶対に throw しません — 順に (1) このインスタンスのオーバーライド → (2) アクティブロケール → (3) extends で指定した継承ロケール → (4) 既定ロケール ko を探し、 それでも見つからなければキー文字列そのものを返し、コンソールに警告を1回だけ残します (「画面に何も出ないこと」より「キーがそのまま見えること」の方がデバッグに向くためです)。 params を渡すと {name} 形式のプレースホルダーを埋めます。

按键查找文案并返回。这是渲染循环(可能每帧被调用的位置)中使用的消费方 API，因此 绝不 throw — 依次查找 (1) 本实例的覆盖 → (2) 活动区域设置 → (3) extends 指定的 继承区域设置 → (4) 默认区域设置 ko；仍然找不到就返回键字符串本身，并且只在控制台留一次警告 (比起「画面上什么都不显示」，「键原样可见」更利于调试)。传入 params 就会填充 {name} 形式的 占位符。