Repository navigation
Template Translations
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 - Which language is shown
- Where a lookup can go
- Steps and placeholders in a text
- Mistakes the card points out
- Writing them in the editor
- When it is shared
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_temperatureThe same two cards, with the profile language set to English and then to French:


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.
Each key is looked for in this order, and the first language that has it wins:
- the viewer's language exactly,
pt-BR - the same language without its region,
pt - English,
en - 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.
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:andgroup:, and the labels of a select's options - the names of its
examples: - the messages of its
checks:, and itsalert:
The card editor shows the declarations in the viewer's language, so the person filling the card in sees Pièce rather than Room:

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.
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.
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.
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.
Getting started
- Home
- Installation
- Quick Start
- Your First Template
- Trying It Out
- Template Builder
- Try a Placeholder
- Try a Template
Core concepts
Content types
Features
- Repeating a Template
- Repeating Sections and Badges
- List Entries
- Page Templates
- Slots
- Templates as Steps
- Sharing Between Dashboards
- Sharing a Template
- Translating a Shared Template
- Visibility
- Checks and Strict
- Styling
- Visual Editors
- Health Card and Badge
- Reading the Debug Report
- Translations
Reference