Icon translations

[frenck]

Context

We just love Material Design Icons. ❤️ Really, we do.

TL;DR: Icons are defined in many places, frontend, backend, and on the integration level. It is all over the place.

We use them everywhere! For example, we use them on entities and, if implemented by the integration, the state of entities.

We also have defaults in some instances if there is a device class, and even those can be state-sensitive. However, in this case, they are not defined in the integration but mainly by the frontend.

That is not all the frontend does; it also has defaults for domains, and sometimes... even more magic. Did you know the frontend will handle adding an icon if, for example, a climate preset "Home" is seen?

This screenshot is odd; in this case, not all presets of my thermostat are known by the frontend. But, adding/defining icons from the backend isn't possible.

Talking about defining them from the backend: Integrations regularly add logic to the backend to make icons more dynamic. The most common examples are found in binary sensors: having different icons for "on" versus "off" and they do so by implementing logic in the icon property.

    @property
    def icon(self) -> str:
        """Return WiFi status sensor icon."""
        return "mdi:wifi" if self.is_on else "mdi:wifi-off"

So, for the context, icons are everywhere. Which is not directly problematic, but it isn't pretty either.

That said, there is one place that is affected by this unneeded: The state machine.
The icons are carried/held in our state machine at runtime, in the cases the integration provided the icon (even if the icon is not dynamic).

I want to address this and propose a solution using this architectural proposal.

Proposal

TL;DR: Introduce an icons.json file, similar to translations. Allowing to set icons for every domain, device class, state, and even state attribute value. It removes the need for them to be defined in both frontend and backend in almost all cases and provides the ability to offer them in even more cases.

Introduce icon translations.

I suggest creating an file that can be defined in each integration (including entity components) called: icons.json, which is the equivalent of the string.json file for languages.

These work pretty much like our normal string translation files, the difference is that this will translate it to MDI icons, and of course, will not have the different languages.

Here is an example of an icons.json file for the Moon integration:

{
  "entity": {
    "sensor": {
      "phase": {
        "default": "mdi:moon",
        "state": {
          "new_moon": "mdi:moon-new",
          "first_quarter": "mdi:moon-first-quarter",
          "full_moon": "mdi:moon-full",
          "last_quarter": "mdi:moon-last-quarter"
        }
      }
    }
  }
}

Ref: https://developers.home-assistant.io/docs/internationalization/core#state-of-entities

Different/new in this structure is the default. Which it the icon that is used by default (for example, when no state matches or when no state is defined).

Entity state attributes

Entity state attributes can be translated as well. Climate presets, as provided in the context of this proposal, are a good example. But we could also add icons to things like select entities (input_select maybe even in the future) and provide button-like interfaces in our Tile cards.

{
  "entity": {
    "climate": {
      "ubercool": {
        "state_attributes": {
          "preset_mode": {
            "default": "mdi:confused",
            "state": {
              "vacation": "mdi:umbrella-beach",
              "night": "mdi:weather-night"
            }
          }
        }
      }
    }
  }
}

Ref: https://developers.home-assistant.io/docs/internationalization/core#entity-state-attributes

Entity components

Entity components are providing the defaults. Include the defaults per device class, and even state attributes. Again, this is the same as we currently do for translations.

{
  "entity_component": {
    "_": {
      "default": "mdi:circle", 
      "state": {
        "off": "mdi:off",
        "on": "mdi:on"
      }
    },
    "problem": {
      "state": {
        "off": "mdi:off",
        "on": "mdi:alert"
      }
    }
  }
}

The _ denotes "no device class" case.

The default property of _ is required in entity components to ensure every domain has a default icon.

Ref: https://developers.home-assistant.io/docs/internationalization/core#state-of-entity-components

Sharing translation keys

All of this would need translation keys. In the first example of the moon integration, the translation key was "phase". The suggestion is not to introduce a new translation key, but to share the icon translation key with the strings translation key.

Reference other icon translations

Our translation have a way to reference other strings. For example, we re-use translations using a syntax that looks like this:

[%key:common::config_flow::description::confirm_setup%]

The proposal is not to bring this logic to the icon translations.

Validation

A nice future expansion that this proposal makes easily possible is to validate that used icons exist. This can be done by adding a script to hassfest that checks this for every PR and commit.

Consequences

There are not many consequences, but let's list them:

• There will be a lot less icons being held in the state machine.
• The frontend has more data to load (besides translations).
• The frontend needs to update all locations that icons are used and even add them to some places (like the climate presets).
• We will probably get a lot of PRs to make this migration happen.
• We will have fewer "icon" property methods in the core codebase.

What will happen with all the old stuff?

We will keep supporting implementing the icon property method on integrations. These are still useful for some dynamic cases that need more complex. Also, we need to keep them around for backward-compatible purposes.

Okay, so there are multiple ways to define it. Which wins?

Good question! Really, again, it's not that different from translations. This is the suggested priority, where the first matching one wins:

1. Icon set in the entity registry (overridden by the end-user).
2. Icon is set on the entity (property method or shorthand).
3. Translation key is set, found in the icons file, and the current state is found in the state key.
4. Translation key is set, found in the icons file and default exists.
5. Device class is set, found in the entity component icons, and the current state is found in that state key.
6. Device class is set, found in the entity component icons, and a default exists.
7. Entity component has _ defined, and the current state is found in the state key.
8. Entity component has _ defined, and the default exists.

Other considered alternatives

• Long ago, I once discussed a proposal to add separate property methods for binary sensors' "on" and "off" states. This proposal goes beyond that.

Note: Many used icons in the examples do not exist. That is fine, it is just an example 😉

[bramkragten]

1 more thing to consider:

There are 2 ways of loading icons in the frontend, all the default domain and state icons SVG's are currently inlined in the code.
This makes these icons super fast, they are there instantly.

For all other icons, that are provided by the integration or the user in the format mdi:icon we have to query a database (that we also have to fill at first usage, by downloading a chunck of the material icons library) to get the correct icon. This takes significantly more time, and can be noticeable.

I would love to have a way to make the default state icons still be super quick, and not having to go through the database.

[frenck]

I would love to have a way to make the default state icons still be super quick, and not having to go through the database.

Yes, agree, that is a more tech problem to solve. I think there are quite a few options in the frontend where we can do smart things. For example, figure out a way to read all icons from all entity components from core, put the into frontend as SVG and basically replace the MDI version during load by the SVG ones (without database lookup).

Or we could consider syncing the icons files from the codebase to the frontend build to fetch all entity components up front / bake them in.

But... yeah, we will have some challenges down the road :)

[balloob]

One approach could be to take core icons and generate a single file that maps them to the mdi SVG. That way you can see in a file that we're importing from a single file and know it's core related.

[chemelli74]

Would be nice to have some core wide defaults for common states, like home/not home for device trackers from routers.
I see many integrations using code similar to:

    @property
    def icon(self) -> str:
        """Return device icon."""
        if self.is_connected:
            return "mdi:lan-connect"
        return "mdi:lan-disconnect"

but not all.
This will allow for more consistency. On top of avoiding copying and paste the same code all over.

[frenck]

That is possible with the above suggestion already? :)

[chemelli74]

I didn't get from your words that there will be a core wide defaults ;-)
Nice it's instead there.

[frenck]

Well device classes are for handling those cases of course

[frenck]

This proposal has been discussed on several occasions and meetings, it has been supported widely, and no other objects or concerns have been raised.

The plan is to move forward with the implementation.

[frenck]

Merged in home-assistant/core#103294

Dev blog: https://developers.home-assistant.io/blog/2024/01/19/icon-translations/

[Nickduino]

Dev blog: https://developers.home-assistant.io/blog/2024/01/19/icon-translations/

Sorry for the silly question, I'm a user and not a developper...Can the end user override it by placing a global icons.json file somewhere?

Concrete example:

The Netatmo integration doesn't state any icon for two of the presets and the thermostat card doesn't allow one to change the icon.