Trans.nvim/doc/Trans.txt

*Trans.txt*             For NVIM v0.8.0             Last change: 2023 March 17

==============================================================================
Table of Contents                                    *Trans-table-of-contents*

1. Trans.nvim                                               |Trans-trans.nvim|
  - 特点                                           |Trans-trans.nvim-特点|
  - 屏幕截图                               |Trans-trans.nvim-屏幕截图|
  - 安装                                           |Trans-trans.nvim-安装|
  - 配置                                           |Trans-trans.nvim-配置|
  - 快捷键绑定                         |Trans-trans.nvim-快捷键绑定|
  - 高亮组                                     |Trans-trans.nvim-高亮组|
  - 声明                                           |Trans-trans.nvim-声明|
  - 感谢                                           |Trans-trans.nvim-感谢|
  - 贡献                                           |Trans-trans.nvim-贡献|
  - 待办 (画大饼)                   |Trans-trans.nvim-待办-(画大饼)|

==============================================================================
1. Trans.nvim                                               *Trans-trans.nvim*


- |Trans-trans.nvim|
    - |Trans-特点|
    - |Trans-屏幕截图|
        - |Trans-演示|
        - |Trans-主题|
    - |Trans-安装|
    - |Trans-配置|
    - |Trans-快捷键绑定|
    - |Trans-高亮组|
    - |Trans-声明|
    - |Trans-感谢|
    - |Trans-贡献|
    - |Trans-待办-(画大饼)|


特点                                               *Trans-trans.nvim-特点*


- 使用纯 lua 编写, 速度极快
      `Lazy.nvim`的记录: `➜  Trans.nvim 0.82ms`
- **可以定义快捷键读英文单词**
      见 wiki
- 大部分功能可以自定义:
    - 高亮
    - 悬浮大小
    - 排版顺序
    - 弹窗大小
    - `舒服窗口动画`
    - etc (更多可以查看|Trans-配置|)
- **完全离线** 的单词翻译体验 (可能后面会支持在线翻译)
- 支持显示:
    - 柯林斯星级
    - 牛津 3000 词汇
    - 中文翻译
    - 英文翻译 (不是英译中, 而是用英文解释)
    - 词根
    - etc
- 舒服的排版和`动画`
- 支持 `normal`和 `visual`模式 > 不支持 visual-block mode
- 本地词库单词量: `430w`


屏幕截图                                   *Trans-trans.nvim-屏幕截图*


演示 ~


https://user-images.githubusercontent.com/107862700/213752097-2eee026a-ddee-4531-bf80-ba2cbc8b44ef.mp4


  视频演示的在线查询, 查询速度取决于你的网络状况
  可以打开音量查看自动读音

https://user-images.githubusercontent.com/107862700/215941500-3293c571-20a1-44e2-b202-77079f158ce9.mp4


主题 ~


  如果你有更美观或者更适合的配色, 欢迎提 PR 主题配色在:
  `lua/Trans/theme.lua`文件中，你只需要添加你主题的表就可以了

- `default`
- `dracula`
- `tokyonight`


安装                                               *Trans-trans.nvim-安装*

_安装之前, 首先需要明确本插件的依赖:_


- ECDICT <https://github.com/skywind3000/ECDICT>: 插件所用的离线单词数据库
- sqlite.lua <https://github.com/kkharji/sqlite.lua>: 操作数据库所用的库
- sqlite3: 数据库

Packer.nvim ~

>lua
    use {
        'JuanZoran/Trans.nvim'
        run = function() require('Trans').install() end, -- 自动下载使用的本地词库
        requires = { 'kkharji/sqlite.lua', },
        -- 如果你不需要任何配置的话, 可以直接按照下面的方式启动
        config = function ()
            require'Trans'.setup{
                -- your configuration here
            }
        end
    }
<

**如果你想要使用 Packer 的惰性加载，这里有一个例子**

>lua
    use {
        "JuanZoran/Trans.nvim",
        keys = {
            { {'n', 'x'}, 'mm' }, -- 换成其他你想用的key即可
            { {'n', 'x'}, 'mk' },
            { 'n', 'mi' },
        },
        run = function() require('Trans').install() end, -- 自动下载使用的本地词库
        requires = { 'kkharji/sqlite.lua',  },
        config = function()
            require("Trans").setup {} -- 启动Trans
            vim.keymap.set({"n", 'x'}, "mm", '<Cmd>Translate<CR>', { desc = ' Translate' }) -- 自动判断virtual 还是 normal 模式
            vim.keymap.set({'n', 'x'}, 'mk', '<Cmd>TransPlay<CR>', {desc = ' 自动发音'}) -- 自动发音选中或者光标下的单词
            vim.keymap.set("n", "mi", "<Cmd>TranslateInput<CR>", { desc = ' Translate' })
        end
    }
<

Lazy.nvim ~

>lua
        {
            "JuanZoran/Trans.nvim",
            keys = {
            -- 可以换成其他你想映射的键
                { 'mm', mode = { 'n', 'x' }, '<Cmd>Translate<CR>', desc = ' Translate' },
                { 'mk', mode = { 'n', 'x' }, '<Cmd>TransPlay<CR>', desc = ' 自动发音' },
    
                -- 目前这个功能的视窗还没有做好，可以在配置里将view.i改成hover
                { 'mi', '<Cmd>TranslateInput<CR>', desc = ' Translate From Input' },
            },
            dependencies = { 'kkharji/sqlite.lua', },
            opts = {
                -- your configuration there
            }
        }
<

**注意事项**:


- `install.sh`
    - 使用了 `wget`下载词库, 安装请确保你的环境变量中存在 wget
    - install.sh 下载后会自动将词库解压, 并移动到 `$HOME/.vim/dict`文件夹下
    - 目前仅在 `Ubuntu22.04`的环境下测试通过
        > 如果上述条件不符合, 请删掉 `run = 'install.sh'`部分, 考虑手动安装词库
        > 如果上述条件满足, 仍出现问题, 欢迎在 issue 里向我反馈,我会及时尝试解决
- 下载词典的过程中, 需要能够 `流畅的访问github下载`
      词库文件压缩包大小为: **281M** 解压缩后的大小大概为: 1.2G
- 安装后如果不能正常运行, 请尝试检查一下问题:
    - 本机是否已经安装了 `sqlite3`
        > Linux 下安装:
        > `sudo pacman -S sqlite # Arch`
        > `sudo apt-get install sqlite3 libsqlite3-dev # Ubuntu`
      后续会增加 `healthcheck` 进行检查
- **auto_play** 使用步骤:
      linux 只需要安装`festival` sudo apt-get install festival festvox-kallpc16k
      **如果你想要设置音色，发音可以访问:** Festival 官方
      <https://www.cstr.ed.ac.uk/projects/festival/morevoices.html>
      可以选择英音、美音、男声、女声
      其他操作系统
    - 需要确保安装了`nodejs`
    - 进入插件的`tts`目录运行`npm install`
        > 如果`install`运行正常则自动安装，如果安装失败，请尝试手动安装
- `title`的配置，只对`neovim 0.9+`版本有效

Festival配置(仅针对linux用户) ~


- 配置文件
    - 全局配置: `/usr/share/festival/siteinit.scm`
    - 用户配置: `~/.festivalrc`
- 更改声音
    - 在 festival 的 voices 文件内建立自己的文件夹
          一般其默认配置目录在`/usr/share/festival/voices`
        示例:
          `sudo mkdir /usr/share/festival/voices/my_voices`
    - 下载想要的 voices 文件并解压
          可能需要 
        - 试听在这里 <https://www.cstr.ed.ac.uk/projects/festival/morevoices.html>)
        - 下载在这里 <http://festvox.org/packed/festival/2.5/voices/>)
            > 假设下载的文件在`Downloads`文件夹, 下载的文件为:`festvox_cmu_us_aew_cg.tar.gz`
        示例:
          `cd ~/Downloads && tar -xf festvox_cmu_us_aew_cg.tar.gz`
    - 将音频文件拷贝到 festival 文件夹 示例:
          `sudo cp -r festival/lib/voices/us/cmu_us_aew_cg/
          /usr/share/festival/voices/my_voices/`
    - 在配置文件中设置默认的声音 示例:
          加入`(set! voice_default voice_cmu_indic_hin_ab_cg)`到配置文件
    - 安装完成
- 相关说明网站 > 可能需要 
    - wiki <https://archlinux.org/packages/community/any/festival-us/> 查看更多详细配置
    - 官方网站 <http://festvox.org/dbs/index.html>
    - 用户手册 <http://www.festvox.org/docs/manual-2.4.0/festival_toc.html>


配置                                               *Trans-trans.nvim-配置*

>lua
    require'Trans'.setup{
        ---@type string the directory for database file and password file
        dir      = os.getenv('HOME') .. '/.vim/dict',
        ---@type table modeStrategy default strategy for mode
        strategy = {
            ---@type { frontend:string, backend:string } fallback strategy for mode
            default = {
                frontend = 'hover',
                backend = '*',
            },
        },
        ---@type table<string, TransBackendOpts> fallback backend for mode
        backend  = {
            ---@class TransBackendOpts
            default = {
                ---@type integer timeout for backend send request
                timeout = 2000,
            },
        },
        ---@type table frontend options
        frontend = {
            ---@class TransFrontendOpts
            ---@field keymaps table<string, string>
            default = {
                ---@type boolean Whether to auto play the audio
                auto_play = true,
                border = 'rounded',
                title = title, -- need nvim-0.9
                ---@type {open: string | boolean, close: string | boolean, interval: integer} Hover Window Animation
                animation = {
                    open = 'slid', -- 'fold', 'slid'
                    close = 'slid',
                    interval = 12,
                },
            },
            ---@class TransHoverOpts : TransFrontendOpts
            hover = {
                ---@type integer Max Width of Hover Window
                width             = 37,
                ---@type integer Max Height of Hover Window
                height            = 27,
                ---@type string -- see: /lua/Trans/style/spinner
                spinner           = 'dots',
                ---@type string -- TODO :support replace with {{special word}}
                fallback_message  = '翻译超时或没有找到相关的翻译',
                auto_resize       = true,
                padding           = 10, -- padding for hover window width
                keymaps           = {
                    -- play         = '_', -- Deprecated
                    pageup       = '[[',
                    pagedown     = ']]',
                    pin          = '<leader>[',
                    close        = '<leader>]',
                    toggle_entry = '<leader>;',
                },
                ---@type string[] auto close events
                auto_close_events = {
                    'InsertEnter',
                    'CursorMoved',
                    'BufLeave',
                },
                ---@type string[] order to display translate result
                order             = {
                    'title',
                    'tag',
                    'pos',
                    'exchange',
                    'translation',
                    'definition',
                },
                ---@type table<string, string>
                icon              = {
                    -- or use emoji
                    star     = '', -- ⭐
                    notfound = ' ', -- ❔
                    yes      = '✔', -- ✔️
                    no       = '', -- ❌
                    cell     = '■', -- ■ | □ | ▇ | ▏ ▎ ▍ ▌ ▋ ▊ ▉ █
                },
            },
        },
        style    = {
            ---@type string global Trans theme [see lua/Trans/style/theme.lua]
            theme = 'default', -- default | tokyonight | dracula
        },
    }
<


快捷键绑定                             *Trans-trans.nvim-快捷键绑定*

**示例:**


  示例中展示, 将`mm`映射成快捷键
>lua
    vim.keymap.set({'n', 'x'}, 'mm', '<Cmd>Translate<CR>')
    vim.keymap.set({'n', 'x'}, 'mk', '<Cmd>TransPlay<CR>') -- 自动发音选中或者光标下的单词
    vim.keymap.set('n', 'mi', '<Cmd>TranslateInput<CR>')
<


高亮组                                         *Trans-trans.nvim-高亮组*


  默认定义
>lua
    {
        TransWord = {
            fg = '#7ee787',
            bold = true,
        },
        TransPhonetic = {
            link = 'Linenr'
        },
        TransTitle = {
            fg = '#0f0f15',
            bg = '#75beff',
            bold = true,
        },
        TransTitleRound = {
            fg = '#75beff',
        },
        TransTag = {
            fg = '#e5c07b',
        },
        TransExchange = {
            link = 'TransTag',
        },
        TransPos = {
            link = 'TransTag',
        },
        TransTranslation = {
            link = 'TransWord',
        },
        TransDefinition = {
            link = 'Moremsg',
        },
        TransWin = {
            link = 'Normal',
        },
        TransBorder = {
            link = 'FloatBorder',
        },
        TransCollins = {
            fg = '#faf743',
            bold = true,
        },
        TransFailed = {
            fg = '#7aa89f',
        },
    }
<


声明                                               *Trans-trans.nvim-声明*


- 本插件词典基于ECDICT <https://github.com/skywind3000/ECDICT>


感谢                                               *Trans-trans.nvim-感谢*


- ECDICT <https://github.com/skywind3000/ECDICT> 本地词典的提供
- sqlite.lua <https://github.com/kharji/sqlite.lua> 数据库访问
- T.vim <https://github.com/sicong-li/T.vim> 灵感来源


贡献                                               *Trans-trans.nvim-贡献*


  更新比较频繁, 文档先鸽了 如果你想要参加这个项目,
  可以提 issue, 我会把文档补齐

待办 (画大饼)                       *Trans-trans.nvim-待办-(画大饼)*


- ☒ 多风格样式查询
- ☒ 重新录制屏幕截图示例
- ☒ 快捷键定义
- ☒ 自动读音
- ☐ 变量命名的支持
- ☐ 历史查询结果保存
- ☐ 在线多引擎异步查询
- ☐ `句子翻译` | `中翻英` 的支持

==============================================================================
2. Links                                                         *Trans-links*

1. *default*: ./theme/default.png
2. *dracula*: ./theme/dracula.png
3. *tokyonight*: ./theme/tokyonight.png

Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>

vim:tw=78:ts=8:noet:ft=help:norl: