Voice style guide

Good sentences match what people say, and nothing else. Good responses tell people what happened, and nothing more. This page collects what works, for every language. Your language leader may have agreements on top of this for your language.

Do not translate the English templates word for word. Think of how people in your language say the command out loud, at home, to a speaker in the corner. Include the short forms ("kitchen lights on") as well as the full ones ("turn on the lights in the kitchen"), and the word orders your language allows.

If your language has a free word order, use permutations, like ({name}; <area>), instead of writing every order out.

Every group of sentences has an example. Write it in your language. It shows reviewers and the progress overview what the group is meant to match.

When the same words keep coming back, like the verbs for turning something on, put them in an expansion rule. Then you improve them in one place. Keep rules simple: no lists inside rules, and no rules inside rules. Otherwise nobody can tell what a template matches.

People add "please" or "can you" to commands. Do not add those words to every template. Put them in the skip words of your language, and the matcher ignores them everywhere.

Every optional part doubles the number of sentences a template matches. A few too many, and your language has millions of sentences, which makes Assist slow on small devices. Check with count_sentences (see Try things out), and prefer a few clear templates over one that matches everything.

A template that is too loose catches sentences that belong to another intent. This happens most with wildcards, which match any text: a loose "play {search_query}" can swallow "set the light to maximum". Put specific words around wildcards. A check on every pull request catches this, but it is easier to avoid it while you write.

Colors, states, and other values that Home Assistant expects in English use the in and out form of a list: your word goes in, the English value comes out.

The repository can write a prompt for an AI model, to get a first draft of the sentences of an intent:

python3 -m script.intentfest llm_template nl HassListAddItem

Treat the output as a draft. You are the native speaker: read every sentence, drop what nobody would say, and add what is missing.

Use the same words and the same form of address as the Home Assistant interface in your language. If your language has agreed on formal or informal address, or on how to translate certain words, follow that. See the language guidelines.

Responses are spoken, so every word counts.

• When a command targets a single device, do not repeat its name. "Turned on the light" is enough.
• When a command targets an area, do not repeat the area or name its entities.
• When a response lists entities, name them all if there are four or fewer. If there are more, name the first three and say how many more there are, like "Kitchen, Hallway, Office and 2 more".

For lists, use the same template as the English responses, so every response reads the same way. Do not write your own variant:

{% if query.matched %}
  {% set match = query.matched | map(attribute="name") | sort | list %}
  {% if match | length > 4 %}
    Yes, {{ match[:3] | join(", ") }} and {{ (match | length - 3) }} more
  {%- else -%}
    Yes,
    {% for name in match -%}
      {% if not loop.first and not loop.last %}, {% elif loop.last and not loop.first %} and {% endif -%}
      {{ name }}
    {%- endfor -%}
  {% endif %}
{% else %}
  No
{% endif %}

Translate the words in it, like "Yes", "No", "and", and "more", and keep the logic as it is.

"The light is on", not "The light was on".

"Turned on the light", not "The light has been turned on".

Covers and valves are the exception. They take a while to open or close, so their responses describe what is happening: "Opening", "Closing".