Enhance error when locale fails to setup

CHANGELOG.md

@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Metadata length validation is buggy for unicode strings #158
 - Pillow 10.4.0 reveals improper type hints for image probing functions #177
+- Enhance error when locale fails to setup #157
 
 ## [3.4.0] - 2024-06-21
 

README.md

@@ -30,6 +30,7 @@ zimscraperlib>=1.1,<1.2
 * Pillow
 * FFmpeg
 * gifsicle (>=1.92)
+* locale (with at least `fr_FR.UTF-8` and `pt_BR.utf8` locales installed for tests to pass)
 
 ## macOS
 
@@ -51,7 +52,7 @@ sudo apt install libmagic1 wget ffmpeg \
 apk add ffmpeg gifsicle libmagic wget libjpeg
 ```
 
-**Nota:** i18n features do not work on Alpine, see https://github.com/openzim/python-scraperlib/issues/134 ; there is one corresponding test which is failing.
+**Nota:** Alpine does not have `locale` support, so i18n features do not work on Alpine, see https://github.com/openzim/python-scraperlib/issues/134 ; there is one corresponding test which is failing.
 
 # Contribution
 

src/zimscraperlib/i18n.py

@@ -56,7 +56,13 @@ def setlocale(root_dir: pathlib.Path, locale_name: str):
     """set the desired locale for gettext.
 
     call this early"""
-    return Locale.setup(root_dir / "locale", locale_name)
+    try:
+        return Locale.setup(root_dir / "locale", locale_name)
+    except locale.Error as exc:
+        raise locale.Error(
+            f"Failed to setup '{locale_name}' locale. If this locale is not installed "
+            "on this system, please install it first."
+        ) from exc
 
 
 def get_iso_lang_data(lang: str) -> tuple[dict, dict | None]: