ha-docs

---

name: ha-docs description: Документация и переводы интеграции Voyah — обновление README.md (двуязычный: русский + английский), strings.json и translations/en.json, ru.json. Использовать при добавлении сущностей, изменении config flow или возможностей интеграции.

Документация и переводы Voyah

Три файла переводов — всегда синхронно

Файл	Роль
custom_components/voyah/strings.json	источник истины (английский)
custom_components/voyah/translations/en.json	точная копия strings.json
custom_components/voyah/translations/ru.json	русский перевод той же структуры

Любое изменение строк UI вносится во все три файла. Структура:

{
  "config": {
    "step": { "<step_id>": { "title", "description", "data", "data_description" } },
    "error": { "<ключ>": "..." },   // ключи из errors["base"] в config_flow.py
    "abort": { "<ключ>": "..." }
  },
  "entity": {
    "sensor":        { "<translation_key>": { "name": "..." } },
    "binary_sensor": { "<translation_key>": { "name": "..." } },
    "button":        { "<translation_key>": { "name": "..." } },
    "device_tracker":{ "<translation_key>": { "name": "..." } }
  }
}

Проверка после правок: python -m json.tool <файл> на каждом из трёх файлов — тесты битый JSON не поймают (сущности в них конструируются напрямую, переводы не загружаются).

README.md — двуязычный

Структура: русская версия сверху, затем якорь <a id="english"></a> со следующим за ним заголовком # English и полная английская копия. Каждое содержательное изменение вносится в обе секции.

Что где документируется:

• Новый сенсор → строка в таблицу «Сенсоры» / "Sensors": название, единица, описание.
• Бинарный сенсор / кнопка / атрибут трекера → соответствующая таблица.
• Нетривиальный алгоритм (как у сенсора окончания зарядки) → отдельный подраздел с пошаговым описанием и крайними случаями. Это стандарт проекта: пользователь должен понимать, откуда берётся значение, без чтения кода.
• Изменение config flow → раздел установки/настройки.
• Особенности данных API (например, SOH > 100% для новой батареи) → примечание рядом с сенсором.

Скриншоты и графики лежат в docs/ (например docs/ha-screenshot.png).

Стиль

• Русский текст: «ёлочки» в кавычках, без англицизмов там, где есть устоявшийся перевод; технические термины API (ключи, эндпоинты) — как в коде, в бэктиках.
• Английские имена сущностей в strings.json — короткие, Sentence case ("Battery temperature", не "The temperature of the battery").
• Русские имена — естественные, без кальки ("Запас хода (электро)", не "Оставшийся пробег").
• Таблицы README — без пустых ячеек; если единицы нет, ставь «—».

Ориентиры Quality Scale по документации

Правила уровней Bronze/Silver/Gold, на которые целимся (подробнее):

• docs-high-level-description — вводный абзац: что это и какой сервис подключает ✅
• docs-installation-instructions — пошаговая установка (HACS + ручная) ✅
• docs-configuration-parameters — описать все параметры (интервал опроса и т.д.)
• docs-supported-functions — таблицы сущностей ✅
• docs-data-update — как и как часто обновляются данные (опрос, интервалы, 12 ч для SOH)
• docs-known-limitations — ограничения (зависимость от облака Voyah Assist, нет push)
• docs-troubleshooting — типовые проблемы: истёкшие токены → reauth, нет машин в аккаунте
• docs-examples — примеры автоматизаций (уведомление о заряде, открытые двери)

При добавлении новых разделов README сверяйся с этим списком — он же чек-лист для повышения уровня качества интеграции.