PyGlossary

一个用于转换词典文件即词汇表的工具。

主要目的是能够在任何操作系统/设备上使用我们的离线词汇表于任何开源词典中。

有无数种格式，而我的时间有限，所以我实现那些对我自己或开源社区来说更有用的格式。同时也考虑到语言的多样性。欢迎提交拉取请求。

截图

<img src="https://yellow-cdn.veclightyear.com/0a4dffa0/4e0a9283-5d9e-46c7-8a61-51bdd8940ed3.png" width="50%" height="50%"/>

Linux - 基于Gtk3的界面

---

<img src="https://yellow-cdn.veclightyear.com/0a4dffa0/70c8cd26-35b6-4852-b09e-8f1e031aea57.png" width="50%" height="50%"/>

Windows - 基于Tkinter的界面

---

<img src="https://yellow-cdn.veclightyear.com/0a4dffa0/14fb5dc1-00d1-4b03-a087-383d7745cd3e.png" width="50%" height="50%"/>

Linux - 命令行界面

---

<img src="https://yellow-cdn.veclightyear.com/0a4dffa0/35ccc002-d7c9-4569-9fb4-9e605af6422f.jpg" width="50%" height="50%"/>

Android Termux - 交互式命令行界面

支持的格式

格式		扩展名	读取	写入
[Aard 2 (slob)](https://github.com/ilius/pyglossary/blob/master/./doc/p/aard2_slob.md	🔢	.slob	✔	✔
[ABBYY Lingvo DSL](https://github.com/ilius/pyglossary/blob/master/./doc/p/dsl.md	📝	.dsl	✔
[Almaany.com](https://github.com/ilius/pyglossary/blob/master/./doc/p/almaany.md (SQLite3，阿拉伯语)	🔢	.db	✔
[AppleDict 二进制](https://github.com/ilius/pyglossary/blob/master/./doc/p/appledict_bin.md	📁	.dictionary	✔	❌
[AppleDict 源文件](https://github.com/ilius/pyglossary/blob/master/./doc/p/appledict.md	📁			✔
[Babylon BGL](https://github.com/ilius/pyglossary/blob/master/./doc/p/babylon_bgl.md	🔢	.bgl	✔	❌
[CC-CEDICT](https://github.com/ilius/pyglossary/blob/master/./doc/p/cc_cedict.md (中文)	📝		✔	❌
[cc-kedict](https://github.com/ilius/pyglossary/blob/master/./doc/p/cc_kedict.md (韩语)	📝		✔	❌
[CSV](https://github.com/ilius/pyglossary/blob/master/./doc/p/csv.md	📝	.csv	✔	✔
[Dict.cc](https://github.com/ilius/pyglossary/blob/master/./doc/p/dict_cc.md (SQLite3，德语)	🔢	.db	✔
[DICT.org / Dictd 服务器](https://github.com/ilius/pyglossary/blob/master/./doc/p/dict_org.md	📁	(📝.index)	✔	✔
[DICT.org / dictfmt 源文件](https://github.com/ilius/pyglossary/blob/master/./doc/p/dict_org_source.md	📝	(.dtxt)		✔
[dictunformat 输出文件](https://github.com/ilius/pyglossary/blob/master/./doc/p/dictunformat.md	📝	(.dictunformat)	✔
[DictionaryForMIDs](https://github.com/ilius/pyglossary/blob/master/./doc/p/dicformids.md	📁	(📁.mids)	✔	✔
[DigitalNK](https://github.com/ilius/pyglossary/blob/master/./doc/p/digitalnk.md (SQLite3，朝鲜语)	🔢	.db	✔
[DIKT JSON](https://github.com/ilius/pyglossary/blob/master/./doc/p/dikt_json.md	📝	(.json)		✔
[EDLIN](https://github.com/ilius/pyglossary/blob/master/./doc/p/edlin.md	📁	.edlin	✔	✔
[EPUB-2 电子书](https://github.com/ilius/pyglossary/blob/master/./doc/p/epub2.md	📦	.epub	❌	✔
[FreeDict](https://github.com/ilius/pyglossary/blob/master/./doc/p/freedict.md	📝	.tei	✔	❌
[Gettext 源文件](https://github.com/ilius/pyglossary/blob/master/./doc/p/gettext_po.md	📝	.po	✔	✔
[HTML 目录 (按文件大小)](https://github.com/ilius/pyglossary/blob/master/./doc/p/html_dir.md	📁		❌	✔
[JMDict](https://github.com/ilius/pyglossary/blob/master/./doc/p/jmdict.md (日语)	📝		✔	❌
[JSON](https://github.com/ilius/pyglossary/blob/master/./doc/p/json.md	📝	.json		✔
[Kobo 电子阅读器词典](https://github.com/ilius/pyglossary/blob/master/./doc/p/kobo.md	📦	.kobo.zip	❌	✔
[Kobo 电子阅读器词典文件](https://github.com/ilius/pyglossary/blob/master/./doc/p/kobo_dictfile.md	📝	.df	✔	✔
[Lingoes 源文件](https://github.com/ilius/pyglossary/blob/master/./doc/p/lingoes_ldf.md	📝	.ldf	✔	✔
[Mobipocket 电子书](https://github.com/ilius/pyglossary/blob/master/./doc/p/mobi.md	🔢	.mobi	❌	✔
[Octopus MDict](https://github.com/ilius/pyglossary/blob/master/./doc/p/octopus_mdict.md	🔢	.mdx	✔	❌
[QuickDic 版本 6](https://github.com/ilius/pyglossary/blob/master/./doc/p/quickdic6.md	📁	.quickdic	✔	✔
[SQL](https://github.com/ilius/pyglossary/blob/master/./doc/p/sql.md	📝	.sql	❌	✔
[StarDict](https://github.com/ilius/pyglossary/blob/master/./doc/p/stardict.md	📁	(📝.ifo)	✔	✔
[StarDict 文本文件](https://github.com/ilius/pyglossary/blob/master/./doc/p/stardict_textual.md	📝	(.xml)	✔	✔
[制表符文件](https://github.com/ilius/pyglossary/blob/master/./doc/p/tabfile.md	📝	.txt, .tab	✔	✔
[Wiktextract](https://github.com/ilius/pyglossary/blob/master/./doc/p/wiktextract.md	📝	.jsonl	✔
[Wordset.org](https://github.com/ilius/pyglossary/blob/master/./doc/p/wordset.md	📁		✔
[XDXF](https://github.com/ilius/pyglossary/blob/master/./doc/p/xdxf.md	📝	.xdxf	✔	❌
[Yomichan](https://github.com/ilius/pyglossary/blob/master/./doc/p/yomichan.md	📦	(.zip)		✔
[Zim (Kiwix)](https://github.com/ilius/pyglossary/blob/master/./doc/p/zim.md	🔢	.zim	✔
图例：

• 📁 目录
• 📝 文本文件
• 📦 包/归档文件
• 🔢 二进制文件
• ✔ 支持
• ❌ 不会支持

注意：基于SQLite的格式不会通过扩展名（.db）来检测； 因此你需要选择格式（通过UI或--read-format标志）。 另外不要将基于SQLite的格式与SQLite模式混淆。

要求

PyGlossary需要Python 3.10或更高版本，并且可以在几乎所有现代操作系统上运行。虽然主要为GNU/Linux设计，但它也能在Windows、Mac OS X和其他基于Unix的操作系统上运行。

如截图所示，有多种用户界面类型（多种使用程序的方式）。

• 基于Gtk3的界面，使用PyGI (Python Gobject Introspection) 你可以在以下系统上安装：

  • Debian/Ubuntu: apt install python3-gi python3-gi-cairo gir1.2-gtk-3.0
  • openSUSE: zypper install python3-gobject gtk3
  • Fedora: dnf install pygobject3 python3-gobject gtk3
  • ArchLinux:
    • pacman -S python-gobject gtk3
    • https://aur.archlinux.org/packages/pyglossary/
  • Mac OS X: brew install pygobject3 gtk+3
  • Nix / NixOS: nix-shell -p pkgs.gobject-introspection python38Packages.pygobject3 python38Packages.pycairo

• 基于Tkinter的界面，在缺少Gtk的情况下可用。特别是在Windows上，Tkinter库随Python一起安装。 你也可以在以下系统上安装：

  • Debian/Ubuntu: apt-get install python3-tk tix
  • openSUSE: zypper install python3-tk tix
  • Fedora: yum install python3-tkinter tix
  • Mac OS X: 阅读 https://www.python.org/download/mac/tcltk/
  • Nix / NixOS: nix-shell -p python38Packages.tkinter tix

• 命令行界面，可以在所有操作系统上无需特定要求即可运行，只需输入：

  python3 main.py --help

  • 交互式命令行界面
    • 要求：pip install prompt_toolkit
    • 非常适合没有GUI的移动设备（如Android上的Termux）
    • 在未传递输出文件参数时自动选择，并且满足以下条件之一：
      • 在Linux上，$DISPLAY环境变量为空或未设置
        • 例如，当你通过SSH使用远程Linux机器时
      • 在Mac上，未找到tkinter模块
    • 使用--cmd或--ui=cmd手动选择
      • 最简单的方式：python3 main.py --cmd
      • 你仍然可以传递输入文件或任何标志/选项
    • 如果同时传递了输入和输出文件，非交互式cmd界面将成为默认选项
    • 如果你正在编写脚本，可以传递--no-interactive来强制禁用交互式界面
      • 然后你必须同时传递输入和输出文件参数
    • 别忘了在提示符中使用上/下或Tab键！
      • 上/下键显示你最近使用的值
      • Tab键显示可用的值/选项
    • 你可以在任何提示符处按Control+C（在Linux/Windows上）退出

UI（用户界面）选择

当你不带任何命令行参数或选项/标志运行PyGlossary时，PyGlossary会尝试找到PyGI并打开基于Gtk3的界面。如果失败，它会尝试找到Tkinter并打开基于Tkinter的界面。如果再次失败，它会尝试找到prompt_toolkit并运行交互式命令行界面。如果这些库都找不到，它会以错误退出。

但你可以使用--ui显式指定用户界面类型

• python3 main.py --ui=gtk
• python3 main.py --ui=tk
• python3 main.py --ui=cmd

在Windows上安装

• 下载并安装Python（3.10或更高版本）
• 打开开始菜单 -> 输入Command -> 右键点击命令提示符 -> 以管理员身份运行
• 确保你有pip，运行：python -m ensurepip --upgrade
• 安装，运行：pip install --upgrade pyglossary
• 现在你应该能够运行pyglossary命令
• 如果找不到命令，确保Python环境变量已设置： <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/3d0e5e94-f346-4576-83dd-d1637d2a4893.png" width="50%" height="50%"/>

特定功能的要求

• 使用按区域设置排序功能需要PyICU

• 使用--remove-html-all标志需要：

  pip install lxml beautifulsoup4

某些格式有额外的要求。 如果你在任何格式上遇到问题，请查看该格式的链接以查看其文档。

在Android上使用Termux？ 请参阅doc/termux.md

配置

参见doc/config.rst。

直接和间接模式

间接模式意味着输入词汇表被完全读取并加载到RAM中，然后转换为输出格式。这是旧版本（3.0.0之前）唯一可用的方法。

直接模式意味着条目被逐一读取、处理并写入输出词汇表。

直接模式的添加是为了限制大型词汇表的内存使用；但在大多数情况下也可能减少转换时间。

将词汇表转换为这些格式需要排序条目：

• StarDict
• EPUB-2
• Mobipocket E-Book

这就是为什么直接模式对这些格式不起作用，PyGlossary必须切换到间接模式（或者之前必须这样做，参见SQLite模式）。

对于其他格式，直接模式将是默认设置。你可以使用--indirect标志覆盖此设置。

SQLite模式

如上所述，将词汇表转换为某些特定格式需要将它们加载到RAM中。 如果词汇表太大无法装入内存,这可能会出现问题。这时你应该尝试在命令中添加--sqlite标志。然后它会使用SQLite3作为中间存储来存储、排序和获取条目。这解决了内存问题,甚至可能减少转换的运行时间(取决于你的主目录存储)。

临时SQLite文件存储在缓存目录中,转换后会被删除(除非你传递--no-cleanup标志)。

如果auto_sqlite 配置参数为true(这是默认值),则在写入这些格式时会自动启用SQLite模式。这也适用于为任何格式传递--sort标志的情况。你可以使用--no-sqlite来覆盖此设置并切换到间接模式。

目前在SQLite模式下无法禁用备选项(--no-alts会被忽略)。

排序

有两种情况可以激活条目排序:

• 输出格式需要排序(如上文所述)
• 你在命令行中传递--sort标志。

如果传递--sort,你还可以传递:

• --sort-key来选择排序键,即排序顺序(包括区域设置),参见doc/sort-key.md

• --sort-encoding来更改用于排序的编码

  • UTF-8是所有排序键和所有输出格式的默认编码(除非另有说明)
  • 这只会影响条目的顺序,不会损坏单词/定义
  • 不可编码的字符会被替换为?字节(仅用于排序)
  • 与--sort-locale冲突

缓存目录

缓存目录用于存储临时文件,这些文件在转换后会被移动或删除。你可以传递--no-cleanup标志以保留它们。

缓存目录的路径:

• Linux或BSD: ~/.cache/pyglossary/
• Mac: ~/Library/Caches/PyGlossary/
• Windows: C:\Users\USERNAME\AppData\Local\PyGlossary\Cache\

用户插件

如果你想添加自己的插件而不将其添加到源代码目录,或者想使用已从存储库中移除的插件,可以将其放在以下目录:

• Linux或BSD: ~/.pyglossary/plugins/
• Mac: ~/Library/Preferences/PyGlossary/plugins/
• Windows: C:\Users\USERNAME\AppData\Roaming\PyGlossary\plugins\

将PyGlossary作为Python库使用

doc/lib-examples目录中有一些示例。

这是一个将任何支持的词汇表格式转换为Tabfile的基本脚本:

import sys
from pyglossary import Glossary

# Glossary.init()应该只被调用一次,所以确保你将它放在正确的位置
Glossary.init()

glos = Glossary()
glos.convert(
	inputFilename=sys.argv[1],
	outputFilename=f"{sys.argv[1]}.txt",
	# 虽然它可以检测*.txt的格式,但你仍可以传递outputFormat
	outputFormat="Tabfile",
	# 你可以以字典形式传递readOptions或writeOptions
	# writeOptions={"encoding": "utf-8"},
)

如果你选择使用glossary_v2:

import sys
from pyglossary.glossary_v2 import ConvertArgs, Glossary

# Glossary.init()应该只被调用一次,所以确保你将它放在正确的位置
Glossary.init()

glos = Glossary()
glos.convert(ConvertArgs(
	inputFilename=sys.argv[1],
	outputFilename=f"{sys.argv[1]}.txt",
	# 虽然它可以检测*.txt的格式,但你仍可以传递outputFormat
	outputFormat="Tabfile",
	# 你可以以字典形式传递readOptions或writeOptions
	# writeOptions={"encoding": "utf-8"},
))

你可以查看Glossary.convert的文档字符串以获取完整的关键字参数列表。

如果你需要在Python程序中添加条目(而不是将一个词汇表转换为另一个),那么你应该使用write而不是convert,这里是一个示例:

from pyglossary import Glossary

Glossary.init()

glos = Glossary()
mydict = {
	"a": "test1",
	"b": "test2",
	"c": "test3",
}
for word, defi in mydict.items():
	glos.addEntryObj(glos.newEntry(
		word,
		defi,
		defiFormat="m",  # "m"表示纯文本, "h"表示HTML
	))

glos.setInfo("title", "My Test StarDict")
glos.setInfo("author", "John Doe")
glos.write("test.ifo", format="Stardict")

注意: 在pyglossary.glossary_v2中,addEntryObj被重命名为addEntry。

注意: 切换到glossary_v2是可选的,但建议使用。

如果你需要将词汇表从文件读入内存中的Glossary对象(而不是立即转换它),你可以使用glos.read(filename, format=inputFormat)。在这种情况下要注意内存使用。

如果你想在创建的词汇表中包含图片、css、js或其他文件,你需要将它们作为数据条目添加,例如:

with open(os.path.join(imageDir, "a.jpeg")) as fp:
	glos.addEntry(glos.newDataEntry("img/a.jpeg", fp.read()))

newDataEntry的第一个参数必须是相对路径(通常是定义的html代码指向的路径)。

内部词汇表结构

词汇表包含多个条目。

每个条目包含:

• 词头(用于查找的标题或主要短语)
• 备选项(一些用于查找的替代短语)
• 定义

在PyGlossary中,词头和备选项一起作为单个Python列表entry.l_word可访问。

entry.defi是定义,为Python Unicode str。另外,entry.b_defi是UTF-8字节数组形式的定义。

entry.defiFormat是定义格式。如果定义是纯文本(非富文本),值为m。如果是HTML(包含任何html标签),则defiFormat为h。XFXF也允许使用值x,但XDXF在词典应用程序中不广泛支持。

还有另一种类型的条目称为数据条目,通常包含输入词汇表中包含的图像、音频、css或任何其他文件。对于数据条目:

• entry.s_word是文件名(而l_word仍然是包含此字符串的列表),
• entry.defiFormat为b
• entry.data给出文件内容的bytes。

条目过滤器

条目过滤器是内部对象，用于修改条目的单词/定义，或在某些特殊情况下删除条目。

它们就像管道中的多个过滤器，连接着"读取器"对象和"写入器"对象（这两个类都在插件中定义并在"词汇表"类中实例化）。

你可以使用配置参数/命令行标志来启用/禁用其中一些过滤器，这些参数在 doc/config.rst 中有详细说明。

完整的条目过滤器列表也在 doc/entry-filters.md 中有详细说明。