diff --git a/blog/2023-11-30-service-exceptions-and-translations.md b/blog/2023-11-30-service-exceptions-and-translations.md index bb0147b0..a80b58f9 100644 --- a/blog/2023-11-30-service-exceptions-and-translations.md +++ b/blog/2023-11-30-service-exceptions-and-translations.md @@ -19,7 +19,7 @@ Integrations should be updated and raise `ServiceValidationError` instead of `Va ## Translation support for Exceptions -The `HomeAssistantError` exception and its subclasses, including `ServiceValidationError`, now accept a translation key to allow localization. [Read more](/docs/internationalization/core/#exceptions). The translation key will be used in cases where the frontend receives information about the exception. +The `HomeAssistantError` exception and its subclasses, including `ServiceValidationError`, now accept a translation key to allow localization. [Read more](/docs/internationalization/core/#exceptions). The translation key will be used in cases where the frontend receives information about the exception. The English error message from the translation cache will also be used to log a message to the console if no custom error message is passed to the exception as argument. ### Background diff --git a/blog/2024-03-15-exception-translations.md b/blog/2024-03-15-exception-translations.md new file mode 100644 index 00000000..5dc28de5 --- /dev/null +++ b/blog/2024-03-15-exception-translations.md @@ -0,0 +1,43 @@ +--- +author: Jan Bouwhuis +authorURL: https://github.com/jbouwh +authorImageURL: https://avatars.githubusercontent.com/u/7188918?s=96&v=4 +title: Raising exceptions with translations +--- + +### Logging exceptions with translation support + +Translation support applies to `HomeAssistantError` and subclasses like `ServiceValidationError`. When a `translation_domain` and `translation_key` is set and the error message is added in `strings.json`, it is no longer needed to add the error message string for the local logging. Home Assistant will automatically fetch the English error message from the translation cache. + +When raising `HomeAssistantError` or a subclass with translation support we should remove the log message from the argument list to enable it to be fetched from the translation cache. + +For example: + +```python +async def async_select_index(hass: HomeAssistant, index: int) -> None: + """Setup the config entry for my device.""" + try: + check_index(index) + except ValueError as exc: + raise ServiceValidationError( + translation_domain=DOMAIN, + translation_key="invalid_index", + translation_placeholders={ + "index": index, + "expected": expected, + }, + ) from exc +``` + +The error message is placed in `strings.json`: + +```json +{ + ... + "exceptions": { + "invalid_index": { + "message": "An invalid index is selected, expected: {expected}, got: {index}" + } + } +} +``` diff --git a/docs/internationalization/core.md b/docs/internationalization/core.md index e720fdbf..67119d3a 100644 --- a/docs/internationalization/core.md +++ b/docs/internationalization/core.md @@ -188,7 +188,6 @@ async def async_select_index(hass: HomeAssistant, index: int) -> None: check_index(index) except ValueError as exc: raise ServiceValidationError( - str(exc), translation_domain=DOMAIN, translation_key="invalid_index", translation_placeholders={ @@ -197,7 +196,6 @@ async def async_select_index(hass: HomeAssistant, index: int) -> None: ) from exc ``` - ### Issues The translation strings for repairs issues are defined under the `issues` key. An example strings file below describes the different supported keys.