---
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 вносится во **все три** файла. Структура:

```json
{
  "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, на которые целимся
([подробнее](https://developers.home-assistant.io/docs/core/integration-quality-scale/)):

- `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 сверяйся с этим списком — он же чек-лист
для повышения уровня качества интеграции.