✨ Features

• 🔤 Translate selected text or word under cursor
• 🪟 Multiple display modes (float, picker)
• 🔍 Auto-detect installed picker
• 📋 Copy translation to clipboard with y
• ⚡ Async translation (non-blocking)

Supported Pickers

⚡ Requirements

• Neovim >= 0.9.0
• curl

Optional (for picker display):

• snacks.nvim, telescope.nvim, fzf-lua, or mini.pick

📦 Installation

lazy.nvim

{
  "acidsugarx/babel.nvim",
  version = "*", -- recomended for the latest tag, not main
  opts = {
    target = "ru",  -- target language
  },
  keys = {
    { "<leader>tr", mode = "v", desc = "Translate selection" },
    { "<leader>tw", desc = "Translate word" },
  },
}

⚙️ Configuration

Minimal Setup

require("babel").setup({
  target = "ru",
})

Full Options

require("babel").setup({
  source = "auto",        -- source language (auto-detect)
  target = "ru",          -- target language
  provider = "google",    -- translation provider: "google", "deepl"
  network = {
    connect_timeout = 5,   -- curl connect timeout in seconds
    request_timeout = 15,  -- max request time in seconds
  },
  cache = {
    enabled = false,       -- enable in-memory translation cache
    limit = 200,           -- max cache entries
  },
  history = {
    enabled = false,       -- keep in-memory translation history
    limit = 20,            -- max saved entries
  },
  fallback_chain = {
    deepl = { "google" }, -- if DeepL fails, try Google
    google = {},
  },
  display = "float",      -- "float" or "picker"
  picker = "auto",        -- "auto", "telescope", "fzf", "snacks", "mini"
  float = {
    border = "rounded",
    mode = "center", -- "center" or "cursor"
    max_width = 80,
    max_height = 20,
    enter = true, -- focus the float window (false = peek without entering)
    auto_close = false, -- close float on CursorMoved in source buffer
    auto_close_ms = 0, -- auto-close delay, 0 = disabled
    pin = true, -- allow pin toggle with `p` when auto-close is enabled
    copy_original = false, -- allow copying original text with `Y`
    nvim_open_win = {}, -- extra nvim_open_win() options (overrides defaults)
  },
  keymaps = {
    translate = "<leader>tr",
    translate_word = "<leader>tw",
    lang = "<leader>tl",
    swap = "<leader>ts",
  },
  -- DeepL provider settings (optional)
  deepl = {
    api_key = nil,        -- or use DEEPL_API_KEY env variable
    pro = nil,            -- nil = auto-detect, true = Pro, false = Free
    formality = "default", -- "default", "more", "less", "prefer_more", "prefer_less"
  },
})

Options

Cursor-follow float preset

For a smaller popup that follows your cursor, use:

require("babel").setup({
  float = {
    mode = "cursor",
    max_width = 60,
    max_height = 10,
  },
})

Peek mode (no-enter + auto-close)

Show a translation popup without entering it. The float closes automatically on the next cursor movement:

require("babel").setup({
  float = {
    mode = "cursor",
    enter = false,
    auto_close = true,
  },
})

Language picker

Change source and target languages interactively:

-- Via command
:BabelLang

-- Via keymap (default <leader>tl)
-- Press <leader>tl, select source, then target

-- Swap source ↔ target
:BabelSwap
-- or press <leader>ts

-- From inside the translation float, press L

Override the language list:

require("babel").setup({
  languages = {
    auto = "Auto-detect",
    en = "English",
    ru = "Russian",
  },
})

Network timeout customization

You can tune provider request timeouts for slow/unstable networks:

require("babel").setup({
  network = {
    connect_timeout = 3,
    request_timeout = 25,
  },
})

Translation history

You can keep the latest successful translations in memory:

require("babel").setup({
  history = {
    enabled = true,
    limit = 50,
  },
})

Fallback chain and cache

You can control provider fallback behavior and enable in-memory caching:

require("babel").setup({
  provider = "deepl",
  fallback_chain = {
    deepl = { "google" },
    google = {},
  },
  cache = {
    enabled = true,
    limit = 500,
  },
})

Float window customization

You can override Babel's default float settings by passing options directly to nvim_open_win():

require("babel").setup({
  float = {
    max_width = 60,
    max_height = 10,
    nvim_open_win = {
      relative = "cursor",
      row = 1,
      col = 0,
      anchor = "NW",
      border = "single",
      title = " Babel ",
    },
  },
})

Language Codes

🚀 Usage

Keymaps

Commands

In Translation Window

🌐 Providers

Provider capabilities

You can inspect provider capabilities from Lua:

local caps = require("babel").get_provider_capabilities()
-- caps.google.supports_formality == false
-- caps.deepl.supports_formality == true

local deepl = require("babel").get_provider_capabilities("deepl")

🧪 Testing: DeepL provider is implemented but needs testing. If you have a DeepL API key and want to help test, please open an issue with your feedback!

🤝 Contributing

Contributions are welcome! Feel free to:

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit pull requests

If you use AI coding assistants, check AGENTS.md for project architecture, quality gates, and safe-change checklist.

🙏 Acknowledgments

Thanks to the amazing Neovim plugin ecosystem:

• folke for snacks.nvim and lazy.nvim
• nvim-telescope for telescope.nvim
• ibhagwan for fzf-lua
• echasnovski for mini.nvim

📝 License

MIT © Ilya Gilev