Skip to content

Template Translations

tempus2016 edited this page Nov 9, 2026 · 1 revision

Translating a Shared Template (v2.10.0+)

A template you share can carry its own words in several languages. Each person who uses it sees them in the language their Home Assistant profile is set to, with nothing to set up on their side.

This page is about the words in a template. The card's own editors and messages are translated separately, in the card itself: see Translations.

On this page:


The language: block

language: holds one mapping per language code, and each holds your texts under keys of your choosing. [[$key]] anywhere in the template is that text; a dotted key, [[$vars.room]], reaches into a nested mapping.

type: custom:decluttering-template-plus
template: room_heating
description: '[[$about]]'
variables:
  - name: room
    label: '[[$vars.room]]'
    description: '[[$vars.room_help]]'
    selector:
      text: {}
    default: Living Room
  - name: temperature
    label: '[[$vars.temperature]]'
    selector:
      entity:
        domain: sensor
    default: sensor.living_room_temperature
language:
  en:
    about: One room's temperature, with the heater switch
    title: Heating
    temperature: Temperature
    heater: Heater
    vars:
      room: Room
      room_help: Shown in the title
      temperature: Temperature sensor
  fr:
    about: La température d'une pièce, avec l'interrupteur du radiateur
    title: Chauffage
    temperature: Température
    heater: Radiateur
    vars:
      room: Pièce
      temperature: Capteur de température
card:
  type: entities
  title: [[$title]]: [[room]]'
  entities:
    - entity: '[[temperature]]'
      name: '[[$temperature]]'
    - entity: switch.cd_heater_switch
      name: '[[$heater]]'
- type: custom:decluttering-card-plus
  template: room_heating
  variables:
    - room: Living Room
    - temperature: sensor.living_room_temperature
- type: custom:decluttering-card-plus
  template: room_heating
  variables:
    - room: Bedroom
    - temperature: sensor.bedroom_temperature

The same two cards, with the profile language set to English and then to French:

Heating: Living Room and Heating: Bedroom, each with Temperature and Heater rows

Chauffage: Living Room and Chauffage: Bedroom, each with Température and Radiateur rows

The values the cards pass, Living Room and Bedroom, are not translated: only the texts in language: are. A change of language builds the card again, and a template card's preview too.

[[$...]] is never a variable. Nothing sets it on a card, and the checks for unset and unused variables leave it alone.


Which language is shown

Each key is looked for in this order, and the first language that has it wins:

  1. the viewer's language exactly, pt-BR
  2. the same language without its region, pt
  3. English, en
  4. the first language the block gives

This goes key by key, so a language that translates half the texts shows the other half from the next language down. In the example, fr has no vars.room_help, so a French viewer gets the English Shown in the title under the Pièce field, and everything else in French. Language codes are matched without minding case, or _ against -, so pt_br answers for pt-BR.

Home Assistant users each pick their own language in their profile, so two people looking at the same dashboard can see it in two languages.


Where a lookup can go

A [[$key]] works anywhere in the content the template builds, and in the parts of it that people read before they build anything:

  • the template's description:
  • a declared variable's label:, description:, helper: and group:, and the labels of a select's options
  • the names of its examples:
  • the messages of its checks:, and its alert:

The card editor shows the declarations in the viewer's language, so the person filling the card in sees Pièce rather than Room:

The card editor in French: the description, the built card in French, and the room field labelled Pièce, with the untranslated helper Shown in the title in English


Steps and placeholders in a text

Steps go after a lookup as after a variable, and a text can hold placeholders of its own, which are filled from the card:

decluttering_templates:
  lang_steps:
    language:
      en:
        title: Heating
        where: Heating in [[room]]
      fr:
        title: Chauffage
        where: 'Chauffage: [[room]]'
    card:
      type: markdown
      content: |
        [[$title|upper]]

        [[$where]]

With room: Kitchen and English, that is HEATING and Heating in Kitchen. A ? works as on a variable: [[$nope?]] gives nothing rather than staying as written.

A template built on another with extends: gets the parent's texts merged with its own, key by key, its own winning:

decluttering_templates:
  lang_child:
    extends: lang_steps
    language:
      en:
        title: Central heating

[[$title|upper]] is now CENTRAL HEATING, and [[$where]] still the parent's.


Mistakes the card points out

A key no language has is left as written, so you see what is missing, and the console names it:

template "typo_demo" looks up titel, which none of its languages has a text for, so it is rendered as written. Add it to the template's language: block.

The template editor's lint finds the same mistake before the card is built, and suggests the key you probably meant:

$titel looks up "titel", which no language in this template's language: block has. Did you mean "title"?

It also warns about a key that one language leaves out while others have it, since that viewer will see another language there:

fr has no text for vars.room_help, which other languages translate, so it shows another language's text there.

A language: that is not a mapping of languages, or a language that is not a mapping of texts, is pointed out as well. A key can be nested a few levels deep, but cannot contain a |, a [, a ] or a ?, since a placeholder could not name it.


Writing them in the editor

In the template editor's code editor, typing [[$ offers the template's texts, its own and the ones it inherits, so you pick a key rather than remember it. Under a variable's Label, a label written as a lookup shows what it comes out as, Shown as: Room.


When it is shared

The language: block is part of the template, so it travels wherever the template does. An export keeps it, written after the parts that read it; an install from a paste or from shared templates keeps it; and so do item templates, templates borrowed from another dashboard and the library dashboard's templates. Whoever installs it sees it in their own language straight away, and can add a language of their own to the block.

When you share one, English is a good first language to include: it is the fallback for anyone whose language the block does not have.

Clone this wiki locally