Move localization to ESPHome compile-time substitutions

docs/addon_climate.md

@@ -34,6 +34,7 @@ substitutions:
   wifi_ssid: !secret wifi_ssid
   wifi_password: !secret wifi_password
   ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+  language: en      # Language code - see docs/localization.md for all supported codes
 
   # Add-on configuration (if needed)
   ## Upload TFT
@@ -68,23 +69,23 @@ packages:
 The following keys are available to be used in your `substitutions`:
 
 <!-- markdownlint-disable MD013 MD033 -->
-Key|Required|Supported values|Default|Description
-:-|:-:|:-:|:-:|:-
-cooler_relay|Mandatory for *cool* and *dual*|`1` or `2`|`0` (disabled)|Relay used to control the cooler. Use `1` for "Relay 1" or `2` for "Relay 2".
-heater_relay|Mandatory for *heat* and *dual*|`1` or `2`|`0` (disabled)|Relay used to control the heater. Use `1` for "Relay 1" or `2` for "Relay 2".
-temp_units|Optional|`°C` or `°F`|`°C`|Temperature unit.
-min_off_time|Optional|Positive integer representing the number of seconds|`300`|Minimum duration (in seconds) the cooling/heating action must be disengaged before it may be engaged.
-min_run_time|Optional|Positive integer representing the number of seconds|`300`|Minimum duration (in seconds) the cooling/heating action must be engaged before it may be disengaged.
-min_idle_time|Optional|Positive integer representing the number of seconds|`30`|Minimum duration (in seconds) the idle action must be active before calling another climate action.
-target_low|Optional|Number representing a temperature in the selected unit|`18` (°C) or `64` (°F)|The initial lower threshold for the target temperature.
-target_high|Optional|Number representing a temperature in the selected unit|`24` (°C) or `75` (°F)|The initial higher threshold for the target temperature.
-temp_min|Optional|Number representing a temperature in the selected unit|*cool: `15` (°C) or `60` (°F)*<br>*heat: `7` (°C) or `45` (°F)*<br>*dual: `7` (°C) or `45` (°F)* |The minimum temperature the climate device can reach. Used to set the range of the frontend gauge.
-temp_max|Optional|Number representing a temperature in the selected unit|*cool: `45` (°C) or `113` (°F)*<br>*heat: `35` (°C) or `95` (°F)*<br>*dual: `45` (°C) or `113` (°F)* |The maximum temperature the climate device can reach. Used to set the range of the frontend gauge.
-~temp_step~|Deprecated|~Number representing a temperature in the selected unit~|~`0.5`~<br>`0.5` (°C) or `1` (°F)|~The granularity with which the target temperature can be controlled.~
-cool_deadband|Optional|Number representing a temperature hysteresis in the selected unit|`0.5` (°C) or `1` (°F)|The minimum temperature differential (temperature above the set point) before engaging cooling.
-cool_overrun|Optional|Number representing a temperature hysteresis in the selected unit|`0.5` (°C) or `1` (°F)|The minimum temperature differential (cooling beyond the set point) before disengaging cooling.
-heat_deadband|Optional|Number representing a temperature hysteresis in the selected unit|`0.5` (°C) or `1` (°F)|The minimum temperature differential (temperature below the set point) before engaging heat.
-heat_overrun|Optional|Number representing a temperature hysteresis in the selected unit|`0.5` (°C) or `1` (°F)|The minimum temperature differential (heating beyond the set point) before disengaging heat.
+| Key | Required | Supported values | Default | Description |
+| :- | :-: | :-: | :-: | :- |
+| cooler_relay | Mandatory for *cool* and *dual* | `1` or `2` | `0` (disabled) | Relay used to control the cooler. Use `1` for "Relay 1" or `2` for "Relay 2". |
+| heater_relay | Mandatory for *heat* and *dual* | `1` or `2` | `0` (disabled) | Relay used to control the heater. Use `1` for "Relay 1" or `2` for "Relay 2". |
+| temp_units | Optional | `°C` or `°F` | `°C` | Temperature unit. |
+| min_off_time | Optional | Positive integer representing the number of seconds | `300` | Minimum duration (in seconds) the cooling/heating action must be disengaged before it may be engaged. |
+| min_run_time | Optional | Positive integer representing the number of seconds | `300` | Minimum duration (in seconds) the cooling/heating action must be engaged before it may be disengaged. |
+| min_idle_time | Optional | Positive integer representing the number of seconds | `30` | Minimum duration (in seconds) the idle action must be active before calling another climate action. |
+| target_low | Optional | Number representing a temperature in the selected unit | `18` (°C) or `64` (°F) | The initial lower threshold for the target temperature. |
+| target_high | Optional | Number representing a temperature in the selected unit | `24` (°C) or `75` (°F) | The initial higher threshold for the target temperature. |
+| temp_min | Optional | Number representing a temperature in the selected unit | *cool: `15` (°C) or `60` (°F)*<br>*heat: `7` (°C) or `45` (°F)*<br>*dual: `7` (°C) or `45` (°F)* | The minimum temperature the climate device can reach. Used to set the range of the frontend gauge. |
+| temp_max | Optional | Number representing a temperature in the selected unit | *cool: `45` (°C) or `113` (°F)*<br>*heat: `35` (°C) or `95` (°F)*<br>*dual: `45` (°C) or `113` (°F)* | The maximum temperature the climate device can reach. Used to set the range of the frontend gauge. |
+| ~temp_step~ | Deprecated | ~Number representing a temperature in the selected unit~ | ~`0.5`~<br>`0.5` (°C) or `1` (°F) | ~The granularity with which the target temperature can be controlled.~ |
+| cool_deadband | Optional | Number representing a temperature hysteresis in the selected unit | `0.5` (°C) or `1` (°F) | The minimum temperature differential (temperature above the set point) before engaging cooling. |
+| cool_overrun | Optional | Number representing a temperature hysteresis in the selected unit | `0.5` (°C) or `1` (°F) | The minimum temperature differential (cooling beyond the set point) before disengaging cooling. |
+| heat_deadband | Optional | Number representing a temperature hysteresis in the selected unit | `0.5` (°C) or `1` (°F) | The minimum temperature differential (temperature below the set point) before engaging heat. |
+| heat_overrun | Optional | Number representing a temperature hysteresis in the selected unit | `0.5` (°C) or `1` (°F) | The minimum temperature differential (heating beyond the set point) before disengaging heat. |
 
 <!-- markdownlint-enable MD013 MD033 -->
 
@@ -104,6 +105,7 @@ substitutions:
   wifi_ssid: !secret wifi_ssid
   wifi_password: !secret wifi_password
   ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+  language: en      # Language code - see docs/localization.md for all supported codes
 
   # Add-on configuration (if needed)
   ## Upload TFT
@@ -146,6 +148,7 @@ substitutions:
   wifi_ssid: !secret wifi_ssid
   wifi_password: !secret wifi_password
   ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+  language: en      # Language code - see docs/localization.md for all supported codes
 
   # Add-on configuration (if needed)
   ## Upload TFT
@@ -188,6 +191,7 @@ substitutions:
   wifi_ssid: !secret wifi_ssid
   wifi_password: !secret wifi_password
   ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+  language: en      # Language code - see docs/localization.md for all supported codes
 
   # Add-on configuration (if needed)
   ## Upload TFT

docs/addon_upload_tft.md

@@ -46,6 +46,7 @@ substitutions:
   wifi_ssid: !secret wifi_ssid
   wifi_password: !secret wifi_password
   ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+  language: en      # Language code - see docs/localization.md for all supported codes
 
   # Add-on configuration (if needed)
   ## Upload TFT
@@ -108,6 +109,7 @@ substitutions:
   wifi_ssid: !secret wifi_ssid
   wifi_password: !secret wifi_password
   ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+  language: en      # Language code - see docs/localization.md for all supported codes
 
   # Upload TFT configuration
   upload_tft_automatically: true
@@ -131,6 +133,7 @@ substitutions:
   wifi_ssid: !secret wifi_ssid
   wifi_password: !secret wifi_password
   ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+  language: en      # Language code - see docs/localization.md for all supported codes
 
   # Disable automatic TFT upload
   upload_tft_automatically: false
@@ -153,6 +156,7 @@ substitutions:
   wifi_ssid: !secret wifi_ssid
   wifi_password: !secret wifi_password
   ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+  language: en      # Language code - see docs/localization.md for all supported codes
 
   # Use a locally hosted TFT file
   nextion_update_url: "http://homeassistant.local:8123/local/nspanel_eu.tft"

docs/api.md

@@ -60,7 +60,7 @@ You can look up the action names available on your Home Assistant instance under
 ### Table of Contents
 <!-- markdownlint-disable MD013 -->
 | Action ID | Action Name | Description |
-|------------|--------------|-------------|
+| --------- | ----------- | ----------- |
 | [`button`](#button-action-button) | [Button Action](#button-action-button) | Configures properties and state of buttons on a specified button page. |
 | [`command`](#command-action-command) | [Command Action](#command-action-command) | Sends a custom command directly to the display. |
 | [`component_color`](#component-color-action-component_color) | [Component Color Action](#component-color-action-component_color) | Changes the foreground color of a specified component on the display. |
@@ -503,7 +503,6 @@ The bitmask values are aligned with the
 - `code_format` (string): Specifies the code format required for arming/disarming the alarm system, such as numeric or alphanumeric.
 - `code_arm_required` (bool): Indicates whether a code is required to arm the system.
 - `entity` (string): The entity ID of the alarm system, used for state updates and control actions.
-- `mui_alarm` (string[]): An array of localized text strings for the alarm control buttons, supporting various alarm states and actions.
 
 **Home Assistant Example:**
 
@@ -516,13 +515,6 @@ data:
   code_format: "number"
   code_arm_required: true
   entity: "alarm_control_panel.home_alarm"
-  mui_alarm:
-    - "Zuhause"
-    - "Abwesend"
-    - "Nacht"
-    - "Urlaub"
-    - "Umgehen"
-    - "Entwaffnen"
 ```
 
 > [!NOTE]
@@ -729,7 +721,7 @@ RTTTL is a compact format for storing melody sequences in a text-based format, m
 This string must conform to the RTTTL format, which includes the melody's name, default settings, and a sequence of notes.
 
 **Example Tones:**
-For example tones and further inspiration, you can visit examples of RTTTL songs [here](https://esphome.io/components/rtttl/#common-beeps).
+For example tones and further inspiration, you can visit this list with [examples of RTTTL songs](https://esphome.io/components/rtttl/#common-beeps).
 
 **Home Assistant Example:**
 

docs/blueprint.md

@@ -9,7 +9,9 @@ The individual elements of the Blueprint are described below.
 
 It is possible to change both the color of the labels and the icons for most of the elements on each screen.
 
-On the blueprint settings, you will be able to select any of the MDI icons supported by Home Assistant, however, your panel will only support the icons available on the [HASwitchPlate Material Design Icons](https://htmlpreview.github.io/?https://github.com/jobr99/Generate-HASP-Fonts/blob/master/cheatsheet.html).
+On the blueprint settings, you will be able to select any of the MDI icons supported by Home Assistant,
+however, your panel will only support the icons available on the
+[HASwitchPlate Material Design Icons](https://htmlpreview.github.io/?https://github.com/jobr99/Generate-HASP-Fonts/blob/master/cheatsheet.html).
 
 For an easier overview, the menu items "Icon Color" and "Label Color" will not be described separately in the following documentation.
 
@@ -26,10 +28,18 @@ This is technically the only required field, as basic functionality will be avai
 
 ### Language for NSPanel
 
-The language can be selected via the drop-down menu.
+Language is no longer configured in the Blueprint. It is now set directly in your ESPHome YAML
+as a substitution, which means only your chosen language's strings are compiled into the firmware —
+saving memory and allowing the panel to display correct date and UI strings even when offline.
 
-Currently around 30 languages are supported, but if you cannot find your language there,
-please create a [new feature request](https://github.com/edwardtfn/NSPanel-Easy/issues/new) and we will be happy to help.
+To set your language, add the `language` substitution to your ESPHome YAML:
+
+```yaml
+substitutions:
+  language: pt  # Portuguese - see docs/localization.md for all supported codes
+```
+
+For the full list of supported language codes, see [Localization](localization.md).
 
 ### Date format
 
@@ -63,7 +73,7 @@ If the value of the sensor needs to be corrected, this can be done via the tempe
 ## Home page - Entities States
 
 | Entity | Description | Example |
-| ---    | ---         | ---     |
+| --- | --- | --- |
 | Home page - Entity State 01-04 (Optional) | Up to four HA entities can be displayed on the home screen. | ![home_page_entity_state_01_04.jpg](pics/home_page_entity_state_01_04.jpg) |
 | Home page - Chips 01-07 (optional) | Used to display icons of HA binary entities on the home screen. The icon is displayed when the entity is on/open/true/active. Otherwise, no icon is displayed. | ![chip](pics/home_page_chips.jpg) |
 | Custom button 01-06 (Optional) | 7 custom buttons that can be assigned to different entities from your Home Assistant. The behavior of these buttons will depend on the entity's domain, such as light, media player, etc. | ![home_page_custom_buttons.jpg](pics/home_page_custom_buttons.jpg) |

docs/customization.md

@@ -75,6 +75,7 @@ substitutions:
   wifi_ssid: !secret wifi_ssid
   wifi_password: !secret wifi_password
   ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+  language: en      # Language code - see docs/localization.md for all supported codes
 
   # Add-on configuration (if needed)
   ## Upload TFT

docs/install.md

@@ -116,6 +116,7 @@ Follow these steps to add a new device in the ESPHome Dashboard:
      wifi_ssid: !secret wifi_ssid
      wifi_password: !secret wifi_password
      ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+     language: en      # Language code - see docs/localization.md for all supported codes
      boot_sound: false
      # Add-on configuration (if needed)
      ## Upload TFT
@@ -226,8 +227,8 @@ The use of a non-conductive tool, like the blue plastic one shown in the picture
       | Panel's Board | TTL USB-to-Serial |
       | :--: | :--: |
       | `3V3` | `VCC`, `3V3`, or `3.3V` |
-      | `TX`  | `RX`  |
-      | `RX`  | `TX`  |
+      | `TX` | `RX` |
+      | `RX` | `TX` |
       | `GND` | `GND` |
       | `IO0` | `GND`<br>This can be connected to a `GND` pin on the panel's board. |
     <!-- markdownlint-enable MD033 -->
@@ -506,6 +507,7 @@ substitutions:
   wifi_ssid: !secret wifi_ssid
   wifi_password: !secret wifi_password
   ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+  language: en      # Language code - see docs/localization.md for all supported codes
   boot_sound: false
   # Add-on configuration (if needed)
   ## Upload TFT
@@ -563,6 +565,7 @@ substitutions:
   wifi_ssid: !secret wifi_ssid
   wifi_password: !secret wifi_password
   ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+  language: en      # Language code - see docs/localization.md for all supported codes
   boot_sound: false
   # Add-on configuration (if needed)
   ## Upload TFT
@@ -607,6 +610,7 @@ substitutions:
   wifi_ssid: !secret wifi_ssid
   wifi_password: !secret wifi_password
   ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+  language: en      # Language code - see docs/localization.md for all supported codes
   boot_sound: false
   # Add-on configuration (if needed)
   ## Upload TFT
@@ -670,6 +674,7 @@ Here's a complete workflow for integrating Bluetooth Proxy while managing memory
      wifi_ssid: !secret wifi_ssid
      wifi_password: !secret wifi_password
      ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+     language: en      # Language code - see docs/localization.md for all supported codes
      boot_sound: false
      # Add-on configuration (if needed)
      ## Upload TFT
@@ -700,6 +705,7 @@ Here's a complete workflow for integrating Bluetooth Proxy while managing memory
      wifi_ssid: !secret wifi_ssid
      wifi_password: !secret wifi_password
      ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+     language: en      # Language code - see docs/localization.md for all supported codes
      boot_sound: false
      # Add-on configuration (if needed)
      ## Upload TFT
@@ -749,6 +755,7 @@ substitutions:
   wifi_ssid: !secret wifi_ssid
   wifi_password: !secret wifi_password
   ota_password: ""  # Optional: set OTA password, or use ${wifi_password} for backward compatibility (see migration guide)
+  language: en      # Language code - see docs/localization.md for all supported codes
   boot_sound: false
   # Add-on configuration (if needed)
   ## Upload TFT