hacs.integration_blueprint: Skill for Claude Code

Translations and icons

translations/en.json is the source of truth for every string a user sees. Home Assistant falls back to the raw key when a string is missing, so a missing key is a visible bug, not a cosmetic one.

Read blueprint.translations.instructions.md first — it holds the rules: placeholder syntax and the single-quote trap that breaks hassfest, why [%key:…%] and strings.json must never appear here, entity translation requirements, which fields accept Markdown, proper nouns, the informal-address rule per language, and cross-language structure. This skill is which keys a given change needs, and how to write them.

The project rule on languages

• Update en.json only. Never edit or create other language files on your own initiative — translations are contributed through the project's translation workflow, and machine-translating them creates churn no maintainer asked for.
• If the developer explicitly asks for another language, confirm which files before starting.
• During feature work, business logic comes first. Use the translation key in code immediately, and fill in en.json either when asked or when the feature is complete.

Key structure

{
  "config": {
    "step": {
      "user": {
        "title": "…",
        "description": "…",
        "data": { "host": "Host" },
        "data_description": { "host": "The hostname or IP address of the device." }
      }
    },
    "error": { "cannot_connect": "…", "invalid_auth": "…", "unknown": "…" },
    "abort": { "already_configured": "…", "reauth_successful": "…" }
  },
  "options": { "step": { "init": { "data": {}, "data_description": {} } } },
  "entity": { "sensor": { "pm25": { "name": "PM2.5", "state": {} } } },
  "services": { "set_target_value": { "name": "…", "description": "…", "fields": {} } },
  "exceptions": { "set_target_value_failed": { "message": "…" } },
  "issues": { "deprecated_api_endpoint": { "title": "…", "description": "…" } },
  "selector": { "mode": { "options": { "auto": "Automatic" }, "unit_of_measurement": "seconds" } },
  "config_subentries": { "device": { "step": { "user": { "data": {} } } } },
  "device": { "gateway": { "name": "…" } },
  "system_health": { "info": { "api_endpoint": "…" } }
}