Initialize localization by loading language resources for the current locale. This function determines the active language from the system locale and the provided `lang_map`, then attempts to load a corresponding JSON file from `locals_dir`. The file name is expected to be ` .j
(
locals_dir: Path,
lang_map: dict[str, str] = LANG_MAP,
default_lang: str = "en_us",
)
| 145 | |
| 146 | |
| 147 | def init_localization( |
| 148 | locals_dir: Path, |
| 149 | lang_map: dict[str, str] = LANG_MAP, |
| 150 | default_lang: str = "en_us", |
| 151 | ) -> tuple[Callable[..., str], str | None]: |
| 152 | """ |
| 153 | Initialize localization by loading language resources for the current locale. |
| 154 | This function determines the active language from the system locale and the |
| 155 | provided `lang_map`, then attempts to load a corresponding JSON file from |
| 156 | `locals_dir`. The file name is expected to be `<lang>.json`, where `<lang>` |
| 157 | is the resolved language code (for example, ``en_us`` or ``zh_cn``). |
| 158 | Parameters |
| 159 | ---------- |
| 160 | locals_dir: |
| 161 | Directory containing localization JSON files. |
| 162 | lang_map: |
| 163 | Mapping from system locale identifiers (e.g. ``"English_United States"``) |
| 164 | or language codes (e.g. ``"en_us"``) to normalized language codes used |
| 165 | to select the JSON file. |
| 166 | default_lang: |
| 167 | Language code to fall back to when the system locale cannot be mapped. |
| 168 | Returns |
| 169 | ------- |
| 170 | tuple[Callable[..., str], str | None] |
| 171 | A pair ``(t, load_error_path)`` where: |
| 172 | * ``t`` is a translation function that takes a string key and optional |
| 173 | keyword arguments and returns a localized, ``str.format``-formatted |
| 174 | string. If the key is missing or formatting fails, it returns the key |
| 175 | or unformatted template. |
| 176 | * ``load_error_path`` is the path to the locale file that failed to load, |
| 177 | or ``None`` if the localization file was loaded successfully. |
| 178 | """ |
| 179 | loc = locale.getlocale() |
| 180 | lang = (loc[0] or "") if loc else "" |
| 181 | |
| 182 | if lang in lang_map: |
| 183 | lang = lang_map[lang] |
| 184 | elif lang.lower() in lang_map: |
| 185 | lang = lang_map[lang.lower()] |
| 186 | else: |
| 187 | lang = default_lang |
| 188 | |
| 189 | lang_res: dict[str, str] = {} |
| 190 | locale_file = locals_dir / f"{lang}.json" |
| 191 | load_error_path: str | None = None |
| 192 | |
| 193 | try: |
| 194 | with open(locale_file, "r", encoding="utf-8") as f: |
| 195 | data = json.load(f) |
| 196 | if isinstance(data, dict): |
| 197 | lang_res = {str(k): str(v) for k, v in data.items()} |
| 198 | except FileNotFoundError: |
| 199 | load_error_path = str(locale_file) |
| 200 | print(Console.err(f"[localization] locale file not found: {locale_file}")) |
| 201 | except json.JSONDecodeError as e: |
| 202 | load_error_path = str(locale_file) |
| 203 | print(Console.err(f"[localization] failed to decode locale json: {locale_file}: {e}")) |
| 204 | except OSError as e: |
no test coverage detected