xython 4.6.3__tar.gz → 4.7.1__tar.gz

{xython-4.6.3/src/xython.egg-info → xython-4.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xython
-Version: 4.6.3
+Version: 4.7.1
 Summary: xython package
 Author-email: "SJ.Park" <sjpkorea@naver.com>
 License: MIT
@@ -19,31 +19,16 @@ Requires-Dist: pymsgbox
 Requires-Dist: pywintypes
 Requires-Dist: win32ui
 
-# 4.5.1 (2026-05-28)
-> - _easy_start.py를 새로 만들어서 사용하기 쉽게 각 모듈을 만들도록 하였읍니다<br>
-> - from xython.xy_easy_start import load; xy = load()<br>
-> - 위와같이 하면, 별도 객체를 만들지 않아도 사용가능하게 만듦<br>
-> - 자세한 사항은 각 참고 자료를 보시면 됩니다. 기존과같이 하여도 작동을 합니다<br>
-# 4.4.1 (2026-05-24)
-> - 각 모듈의 이름을 xy를 맨앞으로 넣는다 (xyexcel, xytime 등)<br>
-> - 매번 들어가는 함수의 이름들은 과감히 제거를 함 (예: for_range, _value 등)<br>
-> - 여러가지를 전체적으로 변경함<br>
-
-# 4.3.8을 기준으로 각 모듈이름을 변경함 (2026-05-16)
-> - 의존성을 줄이기위하여 일부 패키지를 줄이도록 변경<br>
-> - 자동으로 uploader를 사용해서 적용중<br>
-> - 패키지의 일부는 없애고, web용 모듈을 추가함<br>
-
-# 4.0.0을 기준으로 각 모듈이름을 변경함 (2025-03-26)
-> - 쉽게 : **xy_** 접두어로 모든 모듈이름을 변경<br>
-> - 공통 변수모듈 : **xy_xommon**으로 변경<br>
-> - 공통변수이름을 vars => **xvar**로 변경<br>
-
-# About xython Package
+# xython Package에 대하여
 
 >**Functional Programming for Excel, Hwp, Word, Outlook, Color, Etc by win32com<br>
 It can handle for Excel, Hwp, Word, Outlook, Color, Etc by xython**
 
+업무자동화를 위해 Excel, Word, Outlook등을 사용하기 편하게 하기 위해 만든것으로
+각 함수가 독립적인 형태의 결과물이 나오는 함수형으로 만드는 프로그램입니다
+- Python을 사용합니다
+- pywin32를 사용합니다
+- 초보자를 위한 GUI로 사용하는 것과 코딩이 가능한 2가지 방법이 있읍니다
 
 ## xython 패키지는 함수형 프로그램 이다
 
@@ -72,11 +57,10 @@ It can handle for Excel, Hwp, Word, Outlook, Color, Etc by xython**
 
 ### official website
 > oficial document : **https://sjpkorea.github.io/xython.github.io/**<br>
-> oficial website : **www.xython.co.kr  (Korean base)**<br>
+> oficial pypi : **https://pypi.org/project/xython/  (Korean base)**<br>
 
 
 ## components about xython package (패키지의 구성)
-**easy wrapper** for belows;
 
 | 번호 | xython package | 설명                                                |
 |----|----------------|---------------------------------------------------|
@@ -95,7 +79,7 @@ It can handle for Excel, Hwp, Word, Outlook, Color, Etc by xython**
 | 13 | xy_util        | utilities (**for common use**)                    |
 | 14 | xy_auto        | for Keyboard & Mouse control (**for common use**) |
 | 15 | xy_edge        | for edge                                          |
-| 16 | xy_common      | 기본 자료                                          |
+| 16 | xy_common      | xython패키지에 공통으로 사용되는 기본 자료              |
 
 
 ## xython 각 모듈의 간략한 설명
@@ -309,37 +293,63 @@ selenium을 기반으로 사용하기 쉽도록 만든 것
 
 ### 메소드의 이름규칙
 
-| 모듈          | 설명                                              |
-|-------------|-------------------------------------------------|
-| add         | 기존에 있는것의 일반적인 끝에 넣는 것                           |
-| append      | 맨끝에 추가할 때                                       |
-| change      | 입력값을 바꾸는 목적                                     |
-| check       | 확인                                              |
-| control     | 어느 영역안에서 조정을 할 때                                |
-| delete      | 삭제하기                                            |
-| draw        | 선을 그을 때 사용                                      |
-| fill        | 넣기                                              |
-| find        | 찾기                                              |
-| get         | 입력값이 없는 조건에서의 자료를 갖고올때 , read를 제외한 모든 자료를 갖고올 때 |
-| index       | 몇번째의 순서대로 어떤 것을 하는 것                            |
-| input       | 내부적으로 어떤 값을 넣을 때                                |
-| input_dic   | 사전형식일 때                                         |
-| input_l1d   | 1차원 리스트가 입력값일 때                                 |
-| input_l2d   | 2차원 리스트가 입력값일 때                                 |
-| input_value | 숫자형의 자료가 입력될때                                   |
-| insert      | 내가 원하는위치에 넣는 것                                  |
-| make        | 만들기                                             |
-| move        | 이동하기                                            |
-| new         | 새로운것을 만드는 개념                                    |
-| obj         | 객체를 뜻함                                          |
-| paint       | 영역에 색칠하는 것                                      |
-| pick        | 여러개중에서 하나를 갖고올 때                                |
-| read        | 입력값이 있으면서 어떤 자료를 갖고올 때 사용, 보여지는 자료의 값을 갖고올 때    |
-| replace     | 바꾸기                                             |
-| search      | 찾기                                              |
-| select      | 어떤 영역을 선택할 때                                    |
-| set         | 입력값이 특별한것없이 자료를 설정하는 것, 설정값을 변경할 때              |
-| split       | 분리하기                                            |
-| write       | 눈에 보이는 것                                        |
+| 모듈             | 설명                                              |
+|----------------|-------------------------------------------------|
+| add            | 기존에 있는것의 일반적인 끝에 넣는 것                           |
+| append         | 맨끝에 추가할 때                                       |
+| change         | 입력값을 바꾸는 목적                                     |
+| check          | 확인                                              |
+| control        | 어느 영역안에서 조정을 할 때                                |
+| delete         | 삭제하기                                            |
+| draw           | 선을 그을 때 사용                                      |
+| fill           | 넣기                                              |
+| find           | 찾기                                              |
+| get            | 입력값이 없는 조건에서의 자료를 갖고올때 , read를 제외한 모든 자료를 갖고올 때 |
+| index          | 몇번째의 순서대로 어떤 것을 하는 것                            |
+| input          | 내부적으로 어떤 값을 넣을 때                                |
+| input_dic      | 사전형식일 때                                         |
+| input_l1d, l1d | 1차원 리스트가 입력값일 때                                 |
+| input_l2d, l2d | 2차원 리스트가 입력값일 때                                 |
+| input_value    | 숫자형의 자료가 입력될때                                   |
+| insert         | 내가 원하는위치에 넣는 것                                  |
+| make           | 만들기                                             |
+| move           | 이동하기                                            |
+| new            | 새로운것을 만드는 개념                                    |
+| obj            | 객체를 뜻함                                          |
+| paint          | 영역에 색칠하는 것                                      |
+| pick           | 여러개중에서 하나를 갖고올 때                                |
+| read           | 입력값이 있으면서 어떤 자료를 갖고올 때 사용, 보여지는 자료의 값을 갖고올 때    |
+| replace        | 바꾸기                                             |
+| search         | 찾기                                              |
+| select         | 어떤 영역을 선택할 때                                    |
+| set            | 입력값이 특별한것없이 자료를 설정하는 것, 설정값을 변경할 때              |
+| split          | 분리하기                                            |
+| write          | 눈에 보이는 것                                        |
+
+## 주요 버전에 대한 변경내용 설명
+
+### 4.6.3 (2026-09-27)
+> - 전체적으로 함수의 이름을 변경함<br>
+> - xy_re에 추가적인 기능이 가능하도록 기능추가<br>
+> - manul부분만 별도로 하기위해 기본 형태 마련<br>
+
+### 4.5.1 (2026-05-28)
+> - _easy_start.py를 새로 만들어서 사용하기 쉽게 각 모듈을 만들도록 하였읍니다<br>
+> - from xython.xy_easy_start import load; xy = load()<br>
+> - 위와같이 하면, 별도 객체를 만들지 않아도 사용가능하게 만듦<br>
+> - 자세한 사항은 각 참고 자료를 보시면 됩니다. 기존과같이 하여도 작동을 합니다<br>
+### 4.4.1 (2026-05-24)
+> - 각 모듈의 이름을 xy를 맨앞으로 넣는다 (xyexcel, xytime 등)<br>
+> - 매번 들어가는 함수의 이름들은 과감히 제거를 함 (예: for_range, _value 등)<br>
+> - 여러가지를 전체적으로 변경함<br>
 
+### 4.3.8을 기준으로 각 모듈이름을 변경함 (2026-05-16)
+> - 의존성을 줄이기위하여 일부 패키지를 줄이도록 변경<br>
+> - 자동으로 uploader를 사용해서 적용중<br>
+> - 패키지의 일부는 없애고, web용 모듈을 추가함<br>
+
+### 4.0.0을 기준으로 각 모듈이름을 변경함 (2025-03-26)
+> - 쉽게 : **xy_** 접두어로 모든 모듈이름을 변경<br>
+> - 공통 변수모듈 : **xy_xommon**으로 변경<br>
+> - 공통변수이름을 vars => **xvar**로 변경<br>
 

{xython-4.6.3 → xython-4.7.1}/README.md

@@ -1,28 +1,13 @@
-# 4.5.1 (2026-05-28)
-> - _easy_start.py를 새로 만들어서 사용하기 쉽게 각 모듈을 만들도록 하였읍니다<br>
-> - from xython.xy_easy_start import load; xy = load()<br>
-> - 위와같이 하면, 별도 객체를 만들지 않아도 사용가능하게 만듦<br>
-> - 자세한 사항은 각 참고 자료를 보시면 됩니다. 기존과같이 하여도 작동을 합니다<br>
-# 4.4.1 (2026-05-24)
-> - 각 모듈의 이름을 xy를 맨앞으로 넣는다 (xyexcel, xytime 등)<br>
-> - 매번 들어가는 함수의 이름들은 과감히 제거를 함 (예: for_range, _value 등)<br>
-> - 여러가지를 전체적으로 변경함<br>
-
-# 4.3.8을 기준으로 각 모듈이름을 변경함 (2026-05-16)
-> - 의존성을 줄이기위하여 일부 패키지를 줄이도록 변경<br>
-> - 자동으로 uploader를 사용해서 적용중<br>
-> - 패키지의 일부는 없애고, web용 모듈을 추가함<br>
-
-# 4.0.0을 기준으로 각 모듈이름을 변경함 (2025-03-26)
-> - 쉽게 : **xy_** 접두어로 모든 모듈이름을 변경<br>
-> - 공통 변수모듈 : **xy_xommon**으로 변경<br>
-> - 공통변수이름을 vars => **xvar**로 변경<br>
-
-# About xython Package
+# xython Package에 대하여
 
 >**Functional Programming for Excel, Hwp, Word, Outlook, Color, Etc by win32com<br>
 It can handle for Excel, Hwp, Word, Outlook, Color, Etc by xython**
 
+업무자동화를 위해 Excel, Word, Outlook등을 사용하기 편하게 하기 위해 만든것으로
+각 함수가 독립적인 형태의 결과물이 나오는 함수형으로 만드는 프로그램입니다
+- Python을 사용합니다
+- pywin32를 사용합니다
+- 초보자를 위한 GUI로 사용하는 것과 코딩이 가능한 2가지 방법이 있읍니다
 
 ## xython 패키지는 함수형 프로그램 이다
 
@@ -51,11 +36,10 @@ It can handle for Excel, Hwp, Word, Outlook, Color, Etc by xython**
 
 ### official website
 > oficial document : **https://sjpkorea.github.io/xython.github.io/**<br>
-> oficial website : **www.xython.co.kr  (Korean base)**<br>
+> oficial pypi : **https://pypi.org/project/xython/  (Korean base)**<br>
 
 
 ## components about xython package (패키지의 구성)
-**easy wrapper** for belows;
 
 | 번호 | xython package | 설명                                                |
 |----|----------------|---------------------------------------------------|
@@ -74,7 +58,7 @@ It can handle for Excel, Hwp, Word, Outlook, Color, Etc by xython**
 | 13 | xy_util        | utilities (**for common use**)                    |
 | 14 | xy_auto        | for Keyboard & Mouse control (**for common use**) |
 | 15 | xy_edge        | for edge                                          |
-| 16 | xy_common      | 기본 자료                                          |
+| 16 | xy_common      | xython패키지에 공통으로 사용되는 기본 자료              |
 
 
 ## xython 각 모듈의 간략한 설명
@@ -288,37 +272,63 @@ selenium을 기반으로 사용하기 쉽도록 만든 것
 
 ### 메소드의 이름규칙
 
-| 모듈          | 설명                                              |
-|-------------|-------------------------------------------------|
-| add         | 기존에 있는것의 일반적인 끝에 넣는 것                           |
-| append      | 맨끝에 추가할 때                                       |
-| change      | 입력값을 바꾸는 목적                                     |
-| check       | 확인                                              |
-| control     | 어느 영역안에서 조정을 할 때                                |
-| delete      | 삭제하기                                            |
-| draw        | 선을 그을 때 사용                                      |
-| fill        | 넣기                                              |
-| find        | 찾기                                              |
-| get         | 입력값이 없는 조건에서의 자료를 갖고올때 , read를 제외한 모든 자료를 갖고올 때 |
-| index       | 몇번째의 순서대로 어떤 것을 하는 것                            |
-| input       | 내부적으로 어떤 값을 넣을 때                                |
-| input_dic   | 사전형식일 때                                         |
-| input_l1d   | 1차원 리스트가 입력값일 때                                 |
-| input_l2d   | 2차원 리스트가 입력값일 때                                 |
-| input_value | 숫자형의 자료가 입력될때                                   |
-| insert      | 내가 원하는위치에 넣는 것                                  |
-| make        | 만들기                                             |
-| move        | 이동하기                                            |
-| new         | 새로운것을 만드는 개념                                    |
-| obj         | 객체를 뜻함                                          |
-| paint       | 영역에 색칠하는 것                                      |
-| pick        | 여러개중에서 하나를 갖고올 때                                |
-| read        | 입력값이 있으면서 어떤 자료를 갖고올 때 사용, 보여지는 자료의 값을 갖고올 때    |
-| replace     | 바꾸기                                             |
-| search      | 찾기                                              |
-| select      | 어떤 영역을 선택할 때                                    |
-| set         | 입력값이 특별한것없이 자료를 설정하는 것, 설정값을 변경할 때              |
-| split       | 분리하기                                            |
-| write       | 눈에 보이는 것                                        |
+| 모듈             | 설명                                              |
+|----------------|-------------------------------------------------|
+| add            | 기존에 있는것의 일반적인 끝에 넣는 것                           |
+| append         | 맨끝에 추가할 때                                       |
+| change         | 입력값을 바꾸는 목적                                     |
+| check          | 확인                                              |
+| control        | 어느 영역안에서 조정을 할 때                                |
+| delete         | 삭제하기                                            |
+| draw           | 선을 그을 때 사용                                      |
+| fill           | 넣기                                              |
+| find           | 찾기                                              |
+| get            | 입력값이 없는 조건에서의 자료를 갖고올때 , read를 제외한 모든 자료를 갖고올 때 |
+| index          | 몇번째의 순서대로 어떤 것을 하는 것                            |
+| input          | 내부적으로 어떤 값을 넣을 때                                |
+| input_dic      | 사전형식일 때                                         |
+| input_l1d, l1d | 1차원 리스트가 입력값일 때                                 |
+| input_l2d, l2d | 2차원 리스트가 입력값일 때                                 |
+| input_value    | 숫자형의 자료가 입력될때                                   |
+| insert         | 내가 원하는위치에 넣는 것                                  |
+| make           | 만들기                                             |
+| move           | 이동하기                                            |
+| new            | 새로운것을 만드는 개념                                    |
+| obj            | 객체를 뜻함                                          |
+| paint          | 영역에 색칠하는 것                                      |
+| pick           | 여러개중에서 하나를 갖고올 때                                |
+| read           | 입력값이 있으면서 어떤 자료를 갖고올 때 사용, 보여지는 자료의 값을 갖고올 때    |
+| replace        | 바꾸기                                             |
+| search         | 찾기                                              |
+| select         | 어떤 영역을 선택할 때                                    |
+| set            | 입력값이 특별한것없이 자료를 설정하는 것, 설정값을 변경할 때              |
+| split          | 분리하기                                            |
+| write          | 눈에 보이는 것                                        |
+
+## 주요 버전에 대한 변경내용 설명
+
+### 4.6.3 (2026-09-27)
+> - 전체적으로 함수의 이름을 변경함<br>
+> - xy_re에 추가적인 기능이 가능하도록 기능추가<br>
+> - manul부분만 별도로 하기위해 기본 형태 마련<br>
+
+### 4.5.1 (2026-05-28)
+> - _easy_start.py를 새로 만들어서 사용하기 쉽게 각 모듈을 만들도록 하였읍니다<br>
+> - from xython.xy_easy_start import load; xy = load()<br>
+> - 위와같이 하면, 별도 객체를 만들지 않아도 사용가능하게 만듦<br>
+> - 자세한 사항은 각 참고 자료를 보시면 됩니다. 기존과같이 하여도 작동을 합니다<br>
+### 4.4.1 (2026-05-24)
+> - 각 모듈의 이름을 xy를 맨앞으로 넣는다 (xyexcel, xytime 등)<br>
+> - 매번 들어가는 함수의 이름들은 과감히 제거를 함 (예: for_range, _value 등)<br>
+> - 여러가지를 전체적으로 변경함<br>
 
+### 4.3.8을 기준으로 각 모듈이름을 변경함 (2026-05-16)
+> - 의존성을 줄이기위하여 일부 패키지를 줄이도록 변경<br>
+> - 자동으로 uploader를 사용해서 적용중<br>
+> - 패키지의 일부는 없애고, web용 모듈을 추가함<br>
+
+### 4.0.0을 기준으로 각 모듈이름을 변경함 (2025-03-26)
+> - 쉽게 : **xy_** 접두어로 모든 모듈이름을 변경<br>
+> - 공통 변수모듈 : **xy_xommon**으로 변경<br>
+> - 공통변수이름을 vars => **xvar**로 변경<br>
 

{xython-4.6.3 → xython-4.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xython"
-version = "4.6.3"
+version = "4.7.1"
 description = "xython package"
 readme = {file = "README.md", content-type = "text/markdown"}
 requires-python = ">=3.8"

{xython-4.6.3 → xython-4.7.1}/src/xython/__init__.py

@@ -1,12 +1,12 @@
 # __init__.py
-# Copyright (C) 2026 (sjpkorea@naver.com) and contributors
+# Copyright (C) 2025 (sjpkorea@naver.com) and contributors
+
 
-#https://blog.naver.com/xython
 import inspect
 import os
 import sys
 
-__version__ = '4.4.3' #1
+__version__ = '4.3.5' #1
 real_path = os.path.dirname(os.path.abspath(__file__)).replace("\\","/") #2
 sys.path.append(real_path)
 

xython-4.7.1/src/xython/alias_installer.py

@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+"""
+alias_installer.py  (개선판 - 각 모듈의 호출부는 그대로 두면 됨)
+
+방식: 인스턴스마다 alias 를 setattr 하지 않고, __getattr__ 에서 '처음 쓸 때' 만든다.
+  - 인스턴스 생성이 가볍다 (280개 wrapper 를 매번 만들지 않음)
+  - alias -> 원본 역방향 표를 (모듈, 언어) 단위로 1번만 만들고 캐시
+  - 만든 wrapper 는 클래스 단위로 캐시하고, 인스턴스에는 바인딩만 한다
+    (인스턴스 __dict__ 가 깨끗해서 pickle / copy.deepcopy 도 안전)
+  - functools.wraps 로 원본 시그니처 유지 -> help(), IDE 에서 인자 목록이 보인다
+  - make_dir_fallback 을 쓰면 dir()/탭 자동완성에도 alias 가 보인다
+"""
+import difflib, types
+import functools
+from functools import lru_cache
+
+from .locales_loader import load_locales_for_module
+
+
+def _normalize_langs(lang):
+    if lang is None:
+        return ()
+    if isinstance(lang, str):
+        return (lang,)
+    return tuple(lang)
+
+
+def build_combined_doc(orig_name, locales, active_langs):
+    """여러 언어의 doc 을 순서대로 이어 붙인 docstring 생성."""
+    lines = []
+    for lang in active_langs:
+        doc = locales.get(lang, {}).get("docs", {}).get(orig_name)
+        if doc:
+            lines.append(f"[{lang}] {doc}")
+    return "\n".join(lines) if lines else None
+
+
+@lru_cache(maxsize=None)
+def _alias_table(module_name, langs):
+    """(alias -> 원본이름) 역방향 표와 locales 를 반환. langs 는 tuple."""
+    locales = load_locales_for_module(module_name, langs)
+    reverse = {}
+    for lg in langs:
+        for orig, alias in locales[lg]["aliases"].items():
+            if alias and alias != orig:          # 빈 문자열(미번역)은 무시
+                reverse.setdefault(alias, orig)  # 충돌 시 앞쪽 언어가 우선
+    return reverse, locales
+
+
+@lru_cache(maxsize=None)
+def _make_alias_function(owner_cls, module_name, orig_name, alias_name, langs):
+    orig_func = getattr(owner_cls, orig_name, None)
+    if orig_func is None or not callable(orig_func):
+        return None
+
+    _, locales = _alias_table(module_name, langs)
+    doc = build_combined_doc(orig_name, locales, langs) or orig_func.__doc__
+
+    @functools.wraps(orig_func)
+    def wrapper(self, *args, **kwargs):
+        return orig_func(self, *args, **kwargs)
+
+    wrapper.__name__ = alias_name
+    wrapper.__qualname__ = f"{owner_cls.__name__}.{alias_name}"
+    wrapper.__doc__ = doc
+    return wrapper
+
+
+# alias_installer.py
+def install_instance_aliases(instance, module_name, active_langs):
+    langs = _normalize_langs(active_langs)
+    reverse, _ = _alias_table(module_name, langs)          # JSON 캐시 데움
+    owner_cls = type(instance)
+    for alias_name in reverse:
+        # 클래스에 이미 있으면(@alias 로 등록된 것) 건너뜀 → 충돌 방지
+        if hasattr(owner_cls, alias_name):
+            continue
+        func = _make_alias_function(owner_cls, module_name,
+                                    reverse[alias_name], alias_name, langs)
+        if func is not None:
+            # 인스턴스에 바인딩 (인스턴스마다 wrapper 1개씩 생김 — 비용 있음)
+            setattr(instance, alias_name, types.MethodType(func, instance))
+
+
+def make_getattr_fallback(module_name):
+    """클래스에 `__getattr__ = make_getattr_fallback("xy_time")` 로 붙인다."""
+    def _getattr(self, name):
+        if name.startswith("__") and name.endswith("__"):
+            raise AttributeError(name)
+
+        langs = _normalize_langs(self.__dict__.get("lang"))
+        msg = f"'{type(self).__name__}' object has no attribute '{name}'"
+
+        if langs:
+            reverse, _ = _alias_table(module_name, langs)
+            orig = reverse.get(name)
+            if orig is not None:
+                func = _make_alias_function(type(self), module_name, orig, name, langs)
+                if func is not None:
+                    return func.__get__(self, type(self))
+            close = difflib.get_close_matches(name, reverse, n=1)
+            if close:
+                msg += f". Did you mean '{close[0]}'?"
+
+        raise AttributeError(msg)
+
+    return _getattr
+
+
+def make_dir_fallback(module_name):
+    """(선택) 클래스에 `__dir__ = make_dir_fallback("xy_time")` 를 붙이면 자동완성에 alias 가 보인다."""
+    def _dir(self):
+        names = set(object.__dir__(self))
+        langs = _normalize_langs(self.__dict__.get("lang"))
+        if langs:
+            names.update(_alias_table(module_name, langs)[0])
+        return sorted(names)
+
+    return _dir

xython-4.7.1/src/xython/locales_loader.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+"""
+locales_loader.py
+
+locales/{lang}/{module_name}.json 을 읽어서 dict 로 반환.
+- aliases : {원본함수명: 언어별이름}
+- docs    : {원본함수명: 언어별설명}
+"""
+import json
+import os
+
+_LOCALES_DIR = os.path.join(os.path.dirname(__file__), "locales")
+_cache = {}
+
+
+def load_locale(module_name, lang):
+    key = (module_name, lang)
+    if key in _cache:
+        return _cache[key]
+
+    path = os.path.join(_LOCALES_DIR, lang, f"{module_name}.json")
+    if not os.path.exists(path):
+        _cache[key] = {"aliases": {}, "docs": {}}
+        return _cache[key]
+
+    try:
+        # utf-8-sig: 윈도우 메모장/일부 에디터가 붙이는 BOM 이 있어도 읽힌다
+        with open(path, "r", encoding="utf-8-sig") as f:
+            data = json.load(f)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"locale 파일 JSON 오류: {path} ({e})") from e
+
+    result = {
+        "aliases": data.get("aliases", {}),
+        "docs": data.get("docs", {}),
+    }
+    _cache[key] = result
+    return result
+
+
+def load_locales_for_module(module_name, langs):
+    return {lang: load_locale(module_name, lang) for lang in langs}
+
+
+def clear_cache():
+    """JSON 을 고친 뒤 재시작 없이 다시 읽고 싶을 때 (GUI/테스트용)."""
+    _cache.clear()
+    try:
+        from .alias_installer import _alias_table, _make_alias_function
+        _alias_table.cache_clear()
+        _make_alias_function.cache_clear()
+    except ImportError:
+        pass