Localization and Entity Display Formatters¶

2.5.1 · Experimental

Version 2.5.1 adds extended and up-to-date support for localization and formatters.

Localization¶

With version 2.5.1, localization is re-instated and updated with the current Home Assistant localization tags and features, meaning translation support for:

• Platforms (integrations, such as AirVisual)
• Device Classes (motion, power, energy, humidity, etc.)
• Domains (sensors, binary_sensors, etc.)

On top of that, if the translation can't be found using these default translation tags, a specific manual locale_tag can be defined for a state.

Example locale_tag usage¶

The met integration contains the numerical wind direction in degrees. The derived_entity function translates the degrees to 16 named wind directions. The translation for these wind directions is not present in the met component translations, but is in the Home Assistant UI in the form of ui.card.weather.cardinal_direction.<cardinal direction>

The Swiss Army Knife adds the state to this locale_tag and calls the translation engine of Home Assistant to translate the string for display.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

      - type: state
        id: 3
        position:
          cx: 78
          cy: 20
        entity_index: 46
        locale_tag: 'ui.card.weather.cardinal_direction.'
        text:
          before: '/ '
        derived_entity:
          state: |
            [[[
              const DIRECTION = ["n", "nne", "ne", "ene", "e", "ese", "se",
              "sse", "s", "ssw", "sw", "wsw", "w", "wnw", "nw", "nnw", ];
              const dir = Math.floor((state / 22.5) + .5);
              return DIRECTION[(dir % 16)];
            ]]]

Formatters¶

Formatters are an addition to the localization functions to translate a state to a specific - localized - format. Most formatters are about date, datetime and time formats.

Example usage¶

1
2
3
4
5
6
7
8

  - type: 'custom:swiss-army-knife-card'
    entities:
      # - entity: sensor.next_sunrise
      - entity: sun.sun
        attribute: next_rising
        unit: 'uur'
        icon: mdi:weather-sunset-up
        format: time-24h

General formatters¶

DateTime formatters¶

Date formatters¶

Time formatters¶

Difference between Converters and Formatters¶

As of 2.5.1, there is a distinct difference between processing a state (the value coming from Home Assistant) and displaying a state using locale, formats and decimals.