Move localization to ESPHome compile-time substitutions

docs/addon_climate.md

@@ -34,6 +34,7 @@
   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 @@
 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 @@
   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 @@
   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 @@
   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
 

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
@@ -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

docs/localization.md

@@ -0,0 +1,93 @@
+# Localization
+
+NSPanel Easy supports displaying dates, weekdays, and UI strings in your local language.
+Language selection is configured at compile time in your ESPHome YAML, so only the strings for your chosen language
+are loaded onto the device — saving memory and allowing the panel to display correct strings even when offline.
+
+## Setting Your Language
+
+Add the `language` substitution to your ESPHome YAML configuration:
+
+```yaml
+substitutions:
+  device_name: "your_nspanel_name"
+  friendly_name: "Your Panel Name"
+  wifi_ssid: !secret wifi_ssid
+  wifi_password: !secret wifi_password
+  language: pt  # Set your language code here
+```
+
+The default language is `en` (English). If no `language` substitution is set, or if an unsupported code is provided,
+English will be used as a fallback.
+
+After changing the language, you must recompile and flash your panel for the change to take effect.
+
+## Supported Languages
+
+| Code | Language |
+| :--- | :------- |
+| `af` | Afrikaans |
+| `ar` | Arabic |
+| `bg` | Bulgarian |
+| `bn` | Bengali |
+| `bs` | Bosnian |
+| `ca` | Catalan |
+| `cs` | Czech |
+| `cy` | Welsh |
+| `da` | Danish |
+| `de` | German |
+| `el` | Greek |
+| `en` | English *(default)* |
+| `es` | Spanish |
+| `et` | Estonian |
+| `eu` | Basque |
+| `fa` | Persian (Farsi) |
+| `fi` | Finnish |
+| `fr` | French |
+| `gl` | Galician |
+| `he` | Hebrew |
+| `hi` | Hindi |
+| `hr` | Croatian |
+| `hu` | Hungarian |
+| `id` | Indonesian |
+| `is` | Icelandic |
+| `it` | Italian |
+| `ja` | Japanese |
+| `jv` | Javanese |
+| `ko` | Korean |
+| `lt` | Lithuanian |
+| `lv` | Latvian |
+| `mk` | Macedonian |
+| `ms` | Malay |
+| `nb` | Norwegian Bokmål |
+| `nl` | Dutch |
+| `pa` | Punjabi (Gurmukhi) |
+| `pl` | Polish |
+| `pt` | Portuguese |
+| `ro` | Romanian |
+| `ru` | Russian |
+| `sk` | Slovak |
+| `sl` | Slovenian |
+| `sq` | Albanian |
+| `sr` | Serbian |
+| `sv` | Swedish |
+| `sw` | Swahili |
+| `ta` | Tamil |
+| `th` | Thai |
+| `tr` | Turkish |
+| `uk` | Ukrainian |
+| `ur` | Urdu |
+| `vi` | Vietnamese |
+| `zh-cn` | Chinese (Simplified) |
+| `zh-tw` | Chinese (Traditional) |
+
+> [!NOTE]
+> Languages using non-Latin scripts (Arabic, Bengali, Chinese, Cyrillic, Devanagari, Greek, Gurmukhi,
+> Hebrew, Japanese, Korean, Persian, Tamil, Thai, Urdu) require a Nextion TFT font that supports the
+> relevant character set. If your panel displays boxes or question marks instead of characters,
+> your TFT file may not include the required font glyphs.
+
+## Missing Your Language?
+
+If your language is not listed, please [open a feature request](https://github.com/edwardtfn/NSPanel-Easy/issues/new)
+and it will be added in a future release.