immersion.nvim

Language immersion for Neovim. Translates a configurable fraction of the words in your buffer inline, so you pick up vocabulary while reading text that is mostly still in your source language.

Inspired by language-immersion browser extensions, but lives inside Neovim and works on any text or markdown buffer.

Requirements

• Neovim 0.10+
• curl on $PATH
• Internet access (uses the public Google Translate single endpoint)

Install

With lazy.nvim:

{
  "samuelnihoul/immersion.nvim",
  opts = {
    source_lang = "en",
    target_lang = "es",
    ratio = 0.15,
    filetypes = { "markdown", "text", "txt" },
    auto_enable = false,
  },
}

Or call require("immersion").setup({...}) from your own config.

Usage

Command	Effect
:ImmersionEnable	Translate ~ratio of eligible words in the current buffer inline
:ImmersionDisable	Remove all immersion marks from the current buffer
:ImmersionToggle	Toggle the above
:ImmersionRefresh	Recompute the pass (e.g. after editing)
:ImmersionLang <src> <tgt>	Change languages, e.g. :ImmersionLang en zh-CN
:ImmersionRatio <0.0-1.0>	Change fraction of words translated
:ImmersionPeek	Echo the original word under the cursor in the cmdline
:ImmersionHover	Open a floating window with the original word
:ImmersionClearCache	Wipe the translation cache

When immersion is active in a buffer, the original word is shown automatically in a small floating window on CursorHold (the delay is controlled by :set updatetime).

Options

require("immersion").setup({
  source_lang          = "en",
  target_lang          = "es",
  ratio                = 0.15,
  min_word_length      = 4,
  max_words_per_buffer = 200,
  filetypes            = { "markdown", "text", "txt" },
  highlight            = "ImmersionWord",
  auto_enable          = false,
  seed                 = nil,
  timeout_ms           = 5000,
})

seed is optional. Set it to a fixed integer if you want the same words picked across runs of the same buffer.

The translation cache lives at stdpath("cache")/immersion/translations.json.

Highlight

The default ImmersionWord group is a bold yellow. Override it in your colorscheme:

vim.api.nvim_set_hl(0, "ImmersionWord", { fg = "#ffd63a", bold = true })

License

MIT. See LICENSE.