translat.el быстрые переводы в Emacs (inline и posframe) через gptel

Описание

• Мини-режим для Emacs, делающий быстрый перевод выделения или слова под курсором через gptel.
• Два способа показа перевода:
  • Встроенная «подсказка» как inline-оверлей (остается на месте).
  • Всплывающее окно posframe под точкой (исчезает на следующую клавишу).
• По умолчанию перевод из English в Russian и модель gpt-4.1 (всё настраивается).
• Переводы хранятся в памяти, буфер-локально, пока включен режим.

Возможности

• Быстрые клавиши:
  • C-c | — перевод слова/region и показ inline-оверлеем.
  • C-c \ — перевод слова/region и показ во всплывающем posframe (исчезает при следующем нажатии клавиши).
• Гибкая настройка:
  • Языки источника/назначения.
  • Модель и температура для gptel.
  • Префикс/суффикс оверлея и его face.
  • Внешний вид posframe, возможность дублировать показ и через оверлей.
• Хранение истории переводов в текущем буфере.
• Отладочные сообщения по запросу.
• Плавная деградация: если posframe недоступен, вывод в echo-area.

Требования

• Emacs 27.1 или новее.
• gptel 0.9 (https://github.com/karthink/gptel) настроенный на ваш провайдер LLM (OpenAI/OpenRouter/и т.п.).
• posframe 1.4.2 (опционально; без него используется echo-area).
• Сеть и действующий API-ключ для выбранного бэкенда gptel.

Установка

Установка вручную (site-lisp)

• Склонируйте репозиторий:
  • https://github.com/11111000000/translat.el
• Добавьте файл translatel.el в ваш load-path, затем:

  (require 'translatel)
      

Установка через straight.el/use-package

(use-package gptel :ensure t)   ;; настройте gptel отдельно (см. далее)
(use-package posframe :ensure t) ;; опционально
(use-package translatel
  :vc (:url "https://github.com/11111000000/translat.el")
  :init
  ;; опционально — включать режим в текстовых/программных буферах
  (add-hook 'text-mode-hook #'translatel-mode)
  (add-hook 'prog-mode-hook #'translatel-mode))

Doom Emacs

• Добавьте рецепт пакета в packages.el, затем настройте в config.el по аналогии со straight/use-package.
• Настройка gptel (обязательно)

Минимальный пример для OpenAI

(use-package gptel
  :config
  ;; Способ 1: переменная окружения OPENAI_API_KEY
  ;; (setenv "OPENAI_API_KEY" "sk-...")

  ;; Способ 2: через auth-source
  ;; (setq gptel-api-key (auth-source-pick-first-password :host "api.openai.com"))

  ;; Настройка бэкенда (см. README gptel для вариантов)
  (setq gptel-model 'gpt-4o) ;; или используйте модель по умолчанию из translatel
)

Прочие провайдеры

• OpenRouter, Azure OpenAI, локальные модели — смотрите документацию gptel.
• Главное: gptel должен быть работоспособен (API-ключ, endpoint, модель).

Быстрый старт

• Включите режим: M-x translatel-mode.
• Наведите курсор на слово или выделите region.
• Нажмите:
  • C-c | — показать перевод inline (оверлей).
  • C-c \ — показать перевод во всплывающем окне posframe (исчезает на следующую клавишу).
• Для очистки всех оверлеев: M-x translatel-clear-overlays.

Клавиши

• C-c | — translatel-translate-overlay
• C-c \ — translatel-translate-posframe

Поведение

• Если активен region — переводится выделение, иначе берется слово под курсором.
• Если слова нет, переводится символ под курсором.
• Posframe автоматически закрывается следующей командой; можно сделать дублирование в оверлее.
• Оверлеи остаются в буфере до очистки или выключения режима.
• Все переводы (исходный текст, перевод, диапазон, способ показа, время) сохраняются в буфер-локальной истории.

Пользовательские опции (M-x customize-group RET translatel RET)

Языки и стиль

• translatel-source-language
  • Строка, язык-источник (по умолчанию “English”).
• translatel-target-language
  • Строка, язык-приемник (по умолчанию “Russian”).
• Команда формирует системный и пользовательский промпты так, чтобы выводить только перевод — без кавычек и комментариев.

Модель и температура

• translatel-model
  • Символ или строка, например ‘gpt-4.1, ‘gpt-4o, ‘gpt-4o-mini.
  • Значение приводится к символу и пробрасывается в gptel.
• translatel-temperature
  • Число с плавающей точкой (по умолчанию 0.0).

Оверлеи (inline)

• translatel-overlay-prefix
  • Префикс перед переводом в оверлее (по умолчанию ” ⟶ “).
• translatel-overlay-suffix
  • Суффикс после перевода (по умолчанию пусто).
• Лицо (face) для текста перевода в оверлее:
  • translatel-overlay-face (по умолчанию наследует shadow, italic).

Posframe

• translatel-posframe-also-overlay
  • Если t, при показе в posframe параллельно создается и оверлей.
• translatel-posframe-parameters
  • PLIST с параметрами для posframe-show:
    • :poshandler, :border-width, :border-color, :background-color, :foreground-color, :internal-border-width, :respect-header-line, :respect-mode-line.
  • Лицо (face) для текста в posframe:
    • translatel-posframe-face (по умолчанию наследует default).

Отладка

• translatel-debug
  • Если t, печатает подробные отладочные сообщения в Messages.
• Полезные рецепты настройки

Сменить язык и модель

(setq translatel-source-language "English"
      translatel-target-language "Russian"
      translatel-model 'gpt-4o-mini
      translatel-temperature 0.0)

Включать режим повсюду в текстовых/программных буферах

(add-hook 'text-mode-hook #'translatel-mode)
(add-hook 'prog-mode-hook #'translatel-mode)

Красивее оформить подсказки

(setq translatel-overlay-prefix " ⟶ "
      translatel-overlay-suffix "")

(custom-set-faces
 '(translatel-overlay-face
   ((t :inherit shadow :slant italic)))
 '(translatel-posframe-face
   ((t :inherit default)))))

Сделать posframe и оверлей одновременно

(setq translatel-posframe-also-overlay t)

Своя клавиша для очистки оверлеев

(with-eval-after-load 'translatel
  (define-key translatel-mode-map (kbd "C-c C-k") #'translatel-clear-overlays))

История переводов

• Хранится в буфер-локальной переменной translatel–history.
• Формат элемента: plist с ключами
  • :beg :end — диапазон в буфере.
  • :text — исходный текст.
  • :translation — результат перевода.
  • :when — время (current-time).
  • :display — один из символов: overlay | posframe | both | message.
• Посмотреть: M-: (pp translatel–history)
• История очищается при выключении режима.

Команды

• translatel-mode
  • Включить/выключить режим.
• translatel-translate-overlay
  • Перевести и показать оверлеем.
• translatel-translate-posframe
  • Перевести и показать во всплывающем окне posframe (скрывается на следующую команду).
• translatel-clear-overlays
  • Очистить все оверлеи, созданные модом, в текущем буфере.

Как это работает

• При вызове команды вычисляются границы region или слова под курсором.
• Готовится системный промпт «Вы — профессиональный переводчик…» и пользовательский промпт с текстом.
• Дальше вызывается gptel-request с моделью и температурой из настроек translatel.
• Ответ обрабатывается и выводится согласно выбранному способу (overlay/posframe/message).
• Ошибки и пропуски зависимостей логируются в Messages.

Советы и ограничения

• Перевод показывается без кавычек, строго текст — это намеренно.
• Posframe исчезает на следующую клавишу — если нужно «закрепить» перевод, включите translatel-posframe-also-overlay.
• Если posframe не установлен, перевод будет показан через message.
• Нет потоковой передачи (streaming) — запросы синхронно-асинхронные, но без прогресса.
• Хранение истории только в памяти, на время сессии буфера.
• Автоматического определения языков нет — явно задайте source/target, либо поменяйте их в настройках.
• Для нестандартных моделей/провайдеров корректно настройте gptel (API-ключ, endpoint, бэкенд).

Поиск проблем

Нет posframe

• Установите posframe или используйте echo-area (работает автоматически).

Ошибка «gptel not available»

• Проверьте, что gptel установлен и загружается до translatel.

Нет перевода/ошибка API

• Проверьте gptel: API-ключ, модель, соединение.
• Включите (setq translatel-debug t) и посмотрите Messages.

Символ «gptel-request» не найден

• Обновите gptel до ≥ 0.9.

Оверлеи мешают

• M-x translatel-clear-overlays или временно выключите режим.

Примеры полного конфига

;; gptel
(use-package gptel
  :config
  ;; выставите API-ключ/бэкенд согласно документации gptel
  (setq gptel-model 'gpt-4.1
        ;; пример: брать ключ из auth-source
        ;; gptel-api-key (auth-source-pick-first-password :host "api.openai.com")
        ))

;; posframe (опционально)
(use-package posframe :ensure t)

;; translatel
(use-package translatel
  :vc (:url "https://github.com/11111000000/translat.el")
  :init
  (setq translatel-source-language "English"
        translatel-target-language "Russian"
        translatel-model 'gpt-4.1
        translatel-temperature 0.0

        translatel-overlay-prefix " ⟶ "
        translatel-overlay-suffix ""

        translatel-posframe-also-overlay nil
        translatel-posframe-parameters
        '(:poshandler posframe-poshandler-point-bottom-left-corner
          :border-width 1
          :border-color "gray50"
          :background-color "#20232a"
          :foreground-color "#dddddd"
          :internal-border-width 8
          :respect-header-line t
          :respect-mode-line t)

        translatel-debug nil)

  (add-hook 'text-mode-hook #'translatel-mode)
  (add-hook 'prog-mode-hook #'translatel-mode))

Совместимость и платформа

• Emacs 27.1+.
• Тестировалось на GNU/Linux (включая NixOS). Внешних бинарников не требуется.
• Для posframe требуется поддержка child frames в вашей среде.

Планы

• Просмотр и навигация по истории переводов.
• Персистентное сохранение истории.
• Опциональный streaming-режим.
• Расширенная подсветка/копирование и режим «поправить перевод».

Ссылки

• Репозиторий: https://github.com/11111000000/translat.el
• gptel: https://github.com/karthink/gptel
• posframe: https://github.com/tumashu/posframe

Благодарности

• gptel и posframe за отличные базовые библиотеки.

Лицензия MIT