Localize UnsupportedSystemError messages (#4255)

Author: marcelveldt

music_assistant/helpers/util.py

@@ -153,8 +153,11 @@ def verify_system_meets_requirements(
     :raises UnsupportedSystemError: If the system does not meet the requirements.
     """
     if shortfall := _resource_shortfall(min_memory_gb=min_memory_gb, min_cpu_cores=min_cpu_cores):
+        message, translation_key, translation_args = shortfall
         raise UnsupportedSystemError(
-            f"This system does not meet the minimal requirements for {feature_name}: {shortfall}"
+            f"This system does not meet the minimal requirements for {feature_name}: {message}",
+            translation_key=translation_key,
+            translation_args=[feature_name, *translation_args],
         )
     if require_ml_inference:
         verify_cpu_supports_ml_inference()
@@ -178,22 +181,32 @@ def system_meets_requirements(
     return _resource_shortfall(min_memory_gb=min_memory_gb, min_cpu_cores=min_cpu_cores) is None
 
 
-def _resource_shortfall(*, min_memory_gb: float, min_cpu_cores: int) -> str | None:
+def _resource_shortfall(
+    *, min_memory_gb: float, min_cpu_cores: int
+) -> tuple[str, str, list[Any]] | None:
     """
-    Return why the host falls short of the RAM/CPU thresholds, or None if it meets them.
+    Return an unmet RAM/CPU threshold as (message, translation_key, translation_args), or None.
+
+    translation_args exclude the feature name, which the caller prepends.
 
     :param min_memory_gb: Minimum total system RAM in GB (0 disables the check).
     :param min_cpu_cores: Minimum CPU core count (0 disables the check).
     """
     cpu_cores = os.process_cpu_count() or os.cpu_count() or 1
     if min_cpu_cores and cpu_cores < min_cpu_cores:
-        return f"at least {min_cpu_cores} CPU cores are required ({cpu_cores} detected)."
+        return (
+            f"at least {min_cpu_cores} CPU cores are required ({cpu_cores} detected).",
+            "errors.unsupported_system_cpu_cores",
+            [min_cpu_cores, cpu_cores],
+        )
     total_memory_gb = get_total_system_memory()
     # get_total_system_memory() returns 0.0 when the platform cannot report memory
     # (e.g. Windows); treat that as unknown and pass rather than block on a guess.
     if min_memory_gb and total_memory_gb and total_memory_gb < min_memory_gb:
         return (
-            f"at least {min_memory_gb:.0f}GB of RAM is required ({total_memory_gb:.1f}GB detected)."
+            f"at least {min_memory_gb:.0f}GB of RAM is required ({total_memory_gb:.1f}GB detected).",
+            "errors.unsupported_system_memory",
+            [f"{min_memory_gb:.0f}", f"{total_memory_gb:.1f}"],
         )
     return None
 
@@ -215,7 +228,8 @@ def verify_cpu_supports_ml_inference() -> None:
             "On-device audio analysis requires a CPU with AVX2 support "
             "(Intel Haswell / AMD Zen or newer). This CPU does not support AVX2. "
             "If you are running in a virtual machine (e.g. Proxmox), changing the "
-            "CPU type to 'host' may expose AVX2 to the guest."
+            "CPU type to 'host' may expose AVX2 to the guest.",
+            translation_key="errors.unsupported_system_avx2",
         )
 
 

music_assistant/strings.json

@@ -864,6 +864,10 @@
     "audio_error": "An error occurred while processing audio.",
     "queue_empty": "The queue is empty.",
     "unsupported_feature": "This feature is not supported.",
+    "unsupported_system": "This is not supported on this system.",
+    "unsupported_system_cpu_cores": "This system does not meet the minimal requirements for {0}: at least {1} CPU cores are required ({2} detected).",
+    "unsupported_system_memory": "This system does not meet the minimal requirements for {0}: at least {1}GB of RAM is required ({2}GB detected).",
+    "unsupported_system_avx2": "On-device audio analysis requires a CPU with AVX2 support (Intel Haswell / AMD Zen or newer). This CPU does not support AVX2. If you are running in a virtual machine (e.g. Proxmox), changing the CPU type to 'host' may expose AVX2 to the guest.",
     "player_unavailable": "The player is not available.",
     "player_command_failed": "The command to the player failed.",
     "invalid_command": "Invalid or unsupported command.",

music_assistant/translations/en.json

@@ -279,6 +279,10 @@
   "common.errors.setup_required": "Music Assistant is not set up yet.",
   "common.errors.unplayable_media": "This media item cannot be played.",
   "common.errors.unsupported_feature": "This feature is not supported.",
+  "common.errors.unsupported_system": "This is not supported on this system.",
+  "common.errors.unsupported_system_avx2": "On-device audio analysis requires a CPU with AVX2 support (Intel Haswell / AMD Zen or newer). This CPU does not support AVX2. If you are running in a virtual machine (e.g. Proxmox), changing the CPU type to 'host' may expose AVX2 to the guest.",
+  "common.errors.unsupported_system_cpu_cores": "This system does not meet the minimal requirements for {0}: at least {1} CPU cores are required ({2} detected).",
+  "common.errors.unsupported_system_memory": "This system does not meet the minimal requirements for {0}: at least {1}GB of RAM is required ({2}GB detected).",
   "common.media.folder.albums.name": "Albums",
   "common.media.folder.artists.name": "Artists",
   "common.media.folder.audiobooks.name": "Audiobooks",

tests/core/test_helpers.py

@@ -510,6 +510,36 @@ def test_verify_system_meets_requirements_ml_inference() -> None:
         util.verify_system_meets_requirements(feature_name="X", min_cpu_cores=4, min_memory_gb=8.0)
 
 
+def test_unsupported_system_error_translation() -> None:
+    """Each raise path carries the right translation key + ordered args (feature name first)."""
+    with (
+        patch("music_assistant.helpers.util.os.process_cpu_count", return_value=2),
+        patch("music_assistant.helpers.util.get_total_system_memory", return_value=64.0),
+        pytest.raises(UnsupportedSystemError) as cpu_err,
+    ):
+        util.verify_system_meets_requirements(feature_name="Smart Fades", min_cpu_cores=4)
+    assert cpu_err.value.translation_key == "errors.unsupported_system_cpu_cores"
+    assert cpu_err.value.translation_args == ["Smart Fades", 4, 2]
+
+    with (
+        patch("music_assistant.helpers.util.os.process_cpu_count", return_value=16),
+        patch("music_assistant.helpers.util.get_total_system_memory", return_value=2.0),
+        pytest.raises(UnsupportedSystemError) as mem_err,
+    ):
+        util.verify_system_meets_requirements(feature_name="Smart Fades", min_memory_gb=8.0)
+    assert mem_err.value.translation_key == "errors.unsupported_system_memory"
+    assert mem_err.value.translation_args == ["Smart Fades", "8", "2.0"]
+
+    with (
+        patch("music_assistant.helpers.util.platform.machine", return_value="x86_64"),
+        patch("torch.backends.cpu.get_cpu_capability", return_value="DEFAULT"),
+        pytest.raises(UnsupportedSystemError) as avx_err,
+    ):
+        util.verify_cpu_supports_ml_inference()
+    assert avx_err.value.translation_key == "errors.unsupported_system_avx2"
+    assert avx_err.value.translation_args == []
+
+
 @pytest.mark.parametrize(
     ("cpu_cores", "total_gb", "expected"),
     [