agentleFS
hass-energyhass-energy/haeo/.agents/skills/translations/SKILL.md

translations

Skill81 starsChanged 4 days agoMITView on GitHub

User-facing strings in translations/en.json — sensor and device display names and their naming patterns, entity translation keys and placeholders, config flow labels and errors, exception and repair issue messages, and the translation tests that require every used key and no unused ones. Use when adding, renaming, or removing any user-visible string, entity name, or output sensor, or when a translation test fails.

8 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 8 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 8 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Clarity: Write for non-native English speakers

    line 14
  2. Distinctive:

    Abbreviations: Avoid when possible

    line 16
  3. Distinctive:

    Use backticks for: file paths, filenames, variable names, field entries

    line 20
  4. Very specific:

    Read an existing entry in en.json for the shape of each, for example:

    line 26
  5. Distinctive:

    Delete a string in the same change that stops using it.

    line 71
  6. Distinctive:

    All repair issues must be actionable:

    line 82
  7. Distinctive:

    Use translation keys for entity names:

    line 94
  8. Distinctive:

    Use translation keys for user-facing exceptions:

    line 107
  9. Distinctive:

    Do not use parentheses, brackets, or other special characters in display names.

    line 157
  10. Very specific:

    Every entity of an element gets its placeholders from build_translation_placeholders() in entities/translation_placeholders.py.

    line 179
  11. Very specific:

    Every configured field is available by its name, including fields inside sections, and name defaults to the element's title.

    line 180

“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Translation and user-facing text

HAEO uses translations/en.json as a custom integration (not strings.json like core integrations).

Writing style

  • Tone: Friendly and informative
  • Perspective: Second person ("you" and "your")
  • Clarity: Write for non-native English speakers
  • Case: Sentence case for all titles and messages
  • Abbreviations: Avoid when possible

Formatting in messages

  • Use backticks for: file paths, filenames, variable names, field entries
  • Example: "Check the config.json file"

en.json structure

The top-level groups are config (hub flow), options (hub options flow), config_subentries (one group per element type and the network), device, entity, exceptions, issues, selector, services, and common (strings HAEO reads itself). Read an existing entry in en.json for the shape of each, for example:

{
  "config_subentries": {
    "grid": {
      "step": {
        "user": {
          "title": "Grid configuration",
          "data": {
            "connection": "Connection",
            "name": "Grid name"
          },
          "sections": {
            "pricing": {
              "name": "Pricing",
              "data": {
                "price_source_target": "Import price",
                "price_target_source": "Export price"
              }
            }
          }
        }
      },
      "error": {
        "name_exists": "A device with this name already exists"
      }
    }
  },
  "exceptions": {
    "optimization_failed": {
      "message": "The optimization failed: {error}"
    }
  }
}

An element flow's name and connection labels sit in the step's top-level data, because those fields are outside every section. Labels for sectioned fields sit under sections.{section}.data.

Checking translations

These checks keep en.json and the code in step, and all fail CI:

  • test_translations_match_used_keys in translations/tests/test_translations.py requires every key the integration uses to be present, and every key present to be used. Delete a string in the same change that stops using it.
  • The pytest plugin translations/tests/runtime_checks.py runs in every test. It fails a test that shows a flow form, abort, repair issue, translated error, entity name, or enum state whose string or placeholder en.json lacks.
  • translations/tests/flow_messages.py reads each flow's code to find the errors, aborts, and steps its async_step_* methods can reach, so the translation tests require strings for exactly those.

So tests must use real translation keys, never placeholders such as "test_error".

Repair issues

All repair issues must be actionable:

  • Clearly explain what is happening
  • Provide specific steps to resolve (numbered list)
  • Include relevant context (device names, error details)
  • Explain what to expect after following the steps

❌ Bad: "Update firmware" ✅ Good: "Your device firmware version {version} is outdated. To update: 1) Open the manufacturer's app, 2) Navigate to device settings, 3) Select 'Update Firmware'."

Entity translations

Use translation keys for entity names:

class MySensor(SensorEntity):
    _attr_has_entity_name = True
    _attr_translation_key = "battery_power_charge"

Output sensors use the output name as their translation key. Input entities use {element_type}_{field_name}, which elements/field_hints.py builds from the schema.

Exception translations

Use translation keys for user-facing exceptions:

raise HomeAssistantError(
    translation_domain=DOMAIN,
    translation_key="input_unavailable",
    translation_placeholders={"field": field, "element": element, "entities": entities},
)

Icons

Icons live in icons.json, not en.json.

Sensor naming conventions

HAEO uses consistent patterns for sensor translation display names. These patterns affect both the UI display and the generated entity IDs.

Translation key patterns (entity_id generation)

Output names, and so translation keys, use subject-first ordering with an element prefix: {element}_{property}_{qualifier}, such as battery_power_charge, grid_power_import, and battery_state_of_charge.

Display name patterns (UI strings)

Display names follow these patterns for consistency, using sentence case (capital first letter, rest lowercase):

  1. Power sensors: Action + noun pattern

    • ✓ Correct: "Import power", "Export power", "Charge power", "Discharge power", "Active power"
    • ✗ Incorrect: "Power import", "Power export", "Power charge", "Power active"
    • Qualified variants: "{Qualifier} {action} power" (e.g., "Max charge power", "Max discharge power")
  2. Price entities: Qualifier + price pattern

    • ✓ Correct: "Import price", "Export price", "Shortfall price"
    • ✗ Incorrect: "Price (Import)", "Price import"
  3. Shadow price sensors: Constraint description + "shadow price"

    • ✓ Correct: "Max import power shadow price", "Power balance shadow price", "SOC max shadow price"
    • ✗ Incorrect: "Max Import Price (Shadow)", "Shadow Price (Max Import)"
    • Pattern emphasizes "shadow price" as the subject being described
  4. State/status sensors: Noun phrase

    • "State of charge", "Energy stored", "Status"

Avoid special characters

Do not use parentheses, brackets, or other special characters in display names. These characters can interfere with entity ID generation and cause issues.

❌ Bad: "Power (Source to Target)", "Max Import Price (Shadow)" ✅ Good: "{source} to {target} power", "Max import power shadow price"

Parameterized translations

Connection sensors use {source} and {target} placeholders to display the names of the elements they join:

{
  "entity": {
    "sensor": {
      "connection_power": {
        "name": "{source} to {target} power"
      }
    }
  }
}

Every entity of an element gets its placeholders from build_translation_placeholders() in entities/translation_placeholders.py. Every configured field is available by its name, including fields inside sections, and name defaults to the element's title. Parameterize a string with these placeholders rather than writing one string per element type.

Home Assistant entity naming requirements

HAEO follows Home Assistant's entity naming conventions:

Required properties

  • has_entity_name = True - Required for all new integrations
  • translation_key - Used to look up translated entity names
  • translation_placeholders - Optional dict for parameterized translations

Entity name composition

Home Assistant generates friendly_name by combining device and entity names:

  • Entity not in device: friendly_name = entity.name
  • Entity in device with name: friendly_name = f"{device.name} {entity.name}"
  • Entity in device with name=None: friendly_name = device.name

Capitalization

Entity names should start with a capital letter, rest lowercase (unless proper noun or abbreviation):

  • ✓ Correct: "Import power", "State of charge", "SOC max shadow price"
  • ✗ Incorrect: "Import Power", "STATE OF CHARGE"

Documentation references

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.