Huna Arabic — карточки (Telegram Mini App)

Приложение для заучивания арабских слов из курса Huna Arabic (Тома I и II) и учебника «العربية بين يديك» (Байна ядайк, том 2) методом интервального повторения (spaced repetition), в духе Anki.

Что внутри

• index.html, style.css, app.js — само приложение (без сборки, чистый JS)
• words-data.js — словарь: 771 слово с огласовками, разметкой по главам/ диалогам и примерами использования из учебника, по обоим томам
• words-bayna2.js — словарь «العربية بين يديك», том 2: 1492 слова по 16 разделам и дополнительным текстам, внутри разделов — уроки; у 1359 слов есть пример с русским переводом. Файл сгенерирован из таблицы Арабский_том2_карточки.xlsx (лист «По урокам»)
• assets/logo-mark.png — логотип академии
• api/bot-webhook.js — serverless-функция поддержки (см. раздел "Поддержка" ниже)
• Все файлы статические — сборка не требуется (кроме одной serverless- функции для поддержки, которую Vercel подхватывает автоматически)

Как это устроено

Дизайн. Палитра и стиль взяты напрямую с обложек учебников и сайта huna-arabic.com: тёмно-синий градиент (#020a1d → #00264b → #193d61), фирменный тил (#2d6283 / #35a9bf) и акцентный оранжевый (#ff7d1f) из диалогов учебника. Арабский текст — шрифт Noto Naskh Arabic (корректно показывает огласовки), интерфейс — Manrope.

Огласовки. Изначальный Excel-словарь был без огласовок. Текст обоих PDF-учебников был программно сопоставлен со словарём по буквенному "скелету" слова (без учёта огласовок/пробелов/разделителей), после чего огласовки перенесены из учебника в словарь посимвольно. Там, где слово не встречалось в табличном виде в учебнике (числительные, дроби, цвета, некоторые глагольные тройки), огласовки проставлены вручную по правилам литературного арабского. Названия месяцев (январь–декабрь) намеренно оставлены без огласовок — так их принято писать и в самом учебнике. Итоговый исправленный словарь отдельно: vocab_corrected.xlsx.

Интервальное повторение. Планировщик повторяет алгоритм Anki (SM-2, как в планировщике v3 с настройками колоды по умолчанию). Все константы — в начале блока SRS logic в app.js.

Новое слово проходит короткие обучающие шаги — 1 и 10 минут:

• Забыл — снова первый шаг (через 1 минуту).
• Трудно — на первом шаге: середина между 1-м и 2-м шагом (6 минут), дальше — повтор текущего шага.
• Хорошо — следующий шаг; после последнего слово «выпускается» с интервалом 1 день.
• Легко — сразу выпускается с интервалом 4 дня.

Выученное слово повторяется через интервал в днях, у каждого слова свой коэффициент лёгкости (начинается с 250%):

• Забыл — лёгкость −20%, слово уходит на переобучение (шаг 10 минут), после чего возвращается с коротким интервалом.
• Трудно — интервал ×1,2, лёгкость −15%.
• Хорошо — интервал × лёгкость (плюс половина дней просрочки).
• Легко — интервал × лёгкость × 1,3 (плюс все дни просрочки), лёгкость +15%.

Как в Anki: к интервалам добавляется небольшой случайный разброс, чтобы слова, выученные в один день, не приходили всегда пачкой; на кнопках оценки показано, когда слово вернётся («1 мин», «10 мин», «4 дн», «1,5 мес»); день начинается в 4:00 по местному времени; слово, забытое 8 раз, помечается как «трудное слово». Настраиваемый лимит новых слов в день (по умолчанию 15).

Очередь сессии. Следующая карточка выбирается на ходу, как в Anki: сначала слово на обучении, у которого подошло время (забытое минуту назад вернётся через минуту, а не через N карточек), затем повторения и новые слова, новые — равномерно вперемешку с повторениями. Когда они заканчиваются, слова на обучении показываются чуть раньше срока (до 20 минут), так что сессия заканчивается, когда всё выучено. Вверху — три счётчика Anki: синий — новые, красный — на обучении, зелёный — к повторению.

Отмена хода. На экране повторения есть кнопка отмены (стрелка рядом со счётчиком) — она возвращает к предыдущему слову и полностью отменяет последнюю оценку (если случайно нажали не ту кнопку). Доступна только для одного последнего действия, в том числе с экрана завершения сессии.

Разделы: главы и диалоги. Слова размечены по структуре учебника — 16 глав ("Баб", сквозная нумерация через оба тома) и диалоги внутри каждой главы (там, где они есть; вспомогательные страницы — числа, цвета, упражнения — присоединены к диалогу, к которому они относятся). На главном экране кнопка "Раздел" открывает список глав, каждую можно выбрать целиком или раскрыть до отдельных диалогов — можно комбинировать несколько глав/диалогов одновременно. Разметка построена автоматически по заголовкам разделов в PDF учебников.

Active Recall. Карточка сперва показывает только слово на исходном языке; перевод открывается по нажатию — это вынуждает вспоминать значение активно, а не просто узнавать его.

Два направления. На главном экране над кнопкой запуска выбирается режим: «Ар → Рус», «Рус → Ар» или «Оба» (по умолчанию). У направлений полностью независимое расписание повторений — как две разные карточки в Anki с одной колоды note type "с обратной стороной": можно уверенно узнавать слово по-арабски, но ещё учиться вспоминать его написание, и наоборот. Дневной лимит новых карточек действует на каждое направление отдельно.

В режиме «Оба» слово сначала изучается как арабский → русский (узнавание). Как только эта сторона "выпускается" из обучающих шагов в долгосрочный график, открывается обратная карточка — русский → арабский (воспроизведение по памяти, более сложный навык), но не сразу после прямой: между ними проходит хотя бы несколько других карточек. Новые карточки чередуются по направлениям, поэтому обратные встречаются и в коротких занятиях. Если обе стороны слова нужно повторить в один день (или прямая сторона забыта и переучивается), обратная откладывается на завтра — как «отложенные родственные карточки» в Anki.

В режиме «Рус → Ар» доступны все слова: сначала уже знакомые по прямому направлению, затем остальные.

Контекст из учебника. На обратной стороне карточки, под переводом, показан пример настоящего использования слова — короткая фраза из учебника, само слово выделено цветом (подсвечивается целиком, вместе с приставками и окончаниями).

Контексты прошли ручную проверку (октябрь 2026), пример есть у 534 слов из 771:

• убраны неверные совпадения, где подсвечивалось другое слово с похожим написанием (مَدْرَسَة «школа» → مُدَرِّسَة «учительница», سَهْل → سَهَّلَ, خَالَة → خَال и т.п.), а также грамматические таблицы, списки чисел и спряжений вместо живых фраз;
• длинные абзацы (жизнеописание Пророка ﷺ) обрезаны до одной фразы со словом;
• восстановлены обрезанные при извлечении окончания фраз (أَيْضً → أَيْضًا, القُرْآ → القُرْآنَ…) и известные хадисы, оборванные на середине;
• для ~100 слов без примера найдены фразы из того же учебника, где слово встречается (например, خُبْز «хлеб» — из диалога про завтрак).

Для остальных ~237 слов подходящей фразы в извлечённом тексте нет — блок контекста не показывается. Выдуманных примеров нет: только текст учебника.

Главный экран. Сверху — логотип и серия дней, под ними переключатель книг. Главный блок — карточка «Сегодня»: кольцо прогресса за день (сделано / осталось) с числом карточек на сегодня, «ударный режим» за последние 7 дней, примерное время занятия, выбор направления, кнопка запуска и выбор раздела. Ниже — плитки «Числительные», «Месяцы» и «Статистика». Прогресс по книге, томам и направлениям показан на экране «Статистика», там же настройки и поддержка. Карточка «Сегодня» и карточки слов оформлены как «жидкое стекло»: плотная полупрозрачная заливка, блик и светлые края — без размытия фона, поэтому эффект ничего не стоит даже слабым телефонам.

Книги. На главном экране — переключатель учебников (Huna Arabic / العربية بين يديك). У каждой книги свой выбор разделов, своя статистика и свой дневной лимит новых слов; повторения и серия дней общие. На вкладке книги показано, сколько карточек ждёт сегодня. Новую книгу можно добавить так же: отдельный файл со словами (номера слов не должны пересекаться — у «Байна ядайк» они начинаются с 10001, номер тома тоже уникальный: 3) и запись в списке BOOKS в начале app.js. У примеров может быть четвёртый элемент — перевод, он показывается под арабской фразой.

Исламские месяцы. Плитка «Месяцы» на главном экране: список всех 12 месяцев и два режима карточек — по названию вспомнить номер и наоборот. Месяцы учатся только по порядку («первый месяц», «второй месяц»…), без сравнения с январём или февралём, потому что лунный календарь с ними не совпадает. Каждый месяц встречается один раз за круг, забытый возвращается через несколько карточек. Счёт ведётся только в рамках открытого занятия.

Тренажёр числительных. Кнопка «Числительные 1–1000» на главном экране. Случайное число показывается цифрами (и восточноарабскими: ٣٢٥) — его нужно назвать вслух и перевернуть карточку, чтобы свериться; в обратном режиме показана арабская запись, нужно понять число. На обороте — полная запись с огласовками, разбор по частям (300 · 5 · 20) и короткое правило (порядок «единицы и десятки», 11–19, сотни, مِئَة/مِائَة). Диапазоны: 1–10, 11–20, 21–99, 100–1000 и все сразу; число, отмеченное «Не знал», возвращается через несколько карточек. Формы — как при счёте вслух (без исчисляемого существительного); сотня пишется مِئَة, как в «Байна ядайк». Тренажёр не влияет на интервальное повторение слов.

Прогресс. Хранится через Telegram CloudStorage (привязан к аккаунту пользователя в Telegram, доступен с любого устройства). Telegram позволяет не больше 1024 записей на пользователя, а карточек — по две на слово, поэтому прогресс упакован по 25 слов в одну запись (pb_<номер>). Прогресс, сохранённый прежними версиями (по записи на карточку, p_…), при первом запуске автоматически переносится в новый формат, старые записи удаляются. Если приложение открыто вне Telegram (например, в обычном браузере при тестировании), автоматически используется localStorage — тоже работает, но только на этом устройстве и в этом браузере.

Как опубликовать как Telegram Mini App

1. Разместите файлы на HTTPS-хостинге. Подойдёт любой статический хостинг: GitHub Pages, Netlify, Vercel, Cloudflare Pages и т.п. Требование Telegram — обязательно HTTPS. Просто загрузите все файлы из этой папки как есть, ничего собирать не нужно.

2. Создайте бота через @BotFather (если ещё нет): /newbot → укажите имя.

3. Подключите Mini App: /newapp → выберите бота → укажите название, описание, иконку и URL, по которому размещён index.html (из шага 1).

4. Готово. Теперь у бота есть кнопка/меню, открывающая приложение. Можно также добавить кнопку через /mybots → Bot Settings → Menu Button → указать тот же URL.

Поддержка: чтобы пользователи писали боту, а вы это видели

По умолчанию бот, привязанный к Mini App через BotFather, не обрабатывает сообщения — он существует только как "запускатор" приложения. В проект добавлен api/bot-webhook.js — небольшая serverless-функция без базы данных, которая различает три ситуации:

• /start — приветствие ("Ассаламу алейкум!") со ссылкой на само приложение. Никуда не пересылается.
• /support — сначала бот показывает две короткие подсказки (как снять дневной лимит слов; что проверить, если бот не отвечает) с кнопкой "Всё равно написать в поддержку" — только после нажатия бот просит написать вопрос (через Telegram-механизм "ответить на сообщение"); именно ЭТО следующее сообщение пересылается вам в личный чат с ботом. Случайные сообщения без /support не пересылаются — бот вместо этого подскажет написать /support. Текст подсказок — константа SUPPORT_TIPS в начале файла, можно смело менять под свои формулировки.
• Ваш ответ — когда вы отвечаете (Reply в Telegram) на пересланное сообщение, функция определяет исходного отправителя и доставляет ваш ответ ему.

Настройка (после того как проект уже задеплоен на Vercel):

1. Узнайте свой числовой Telegram ID — напишите /start боту @userinfobot, он пришлёт ваш Id.
2. В Vercel: Project → Settings → Environment Variables — добавьте:
   • BOT_TOKEN — токен вашего бота (тот, что выдал @BotFather при создании; если забыли — /mybots → выберите бота → API Token)
   • OWNER_CHAT_ID — ваш ID из шага 1
   • MINI_APP_URL — ссылка, которую бот присылает по /start. Лучший вариант — прямая ссылка на приложение вида https://t.me/huna_arabic_appbot/имя_приложения (имя приложения задавали при /newapp в BotFather) — она открывает Mini App прямо в Telegram. Подойдёт и обычный https-адрес хостинга, но тогда приложение откроется как обычный сайт, а не как Mini App внутри Telegram. Если переменную не задать, бот просто не пришлёт ссылку.
3. Redeploy проект (Deployments → ⋯ → Redeploy), чтобы переменные подхватились.
4. Установите вебхук — один раз откройте в браузере (подставив свой токен и домен без угловых скобок):

   https://api.telegram.org/bot<BOT_TOKEN>/setWebhook?url=https://<ваш-домен-на-vercel>/api/bot-webhook
   

   В ответ должно прийти {"ok":true,"result":true,...}.

Кнопка "Написать в поддержку" на экране статистики ведёт на t.me/huna_arabic_appbot (username уже указан в app.js, константа SUPPORT_BOT_USERNAME).

Как пользоваться: пользователь отправляет боту /support, пишет вопрос в ответ на просьбу бота — сообщение придёт вам как пересланное. Ответьте на него (именно Reply, не новое сообщение) — ответ уйдёт исходному пользователю.

Ограничение: если пользователь в настройках приватности Telegram скрыл "пересылку от себя", бот не сможет определить, кому отвечать — в этом случае в вашем чате появится соответствующее уведомление. Это редкая настройка, не критично для большинства пользователей.

Возможные доработки на будущее

• Режим "напишите перевод" вместо самооценки (более строгий Active Recall)
• Аудио-произношение слов
• Групповая/семейная статистика через shared CloudStorage