{"id":17654286,"url":"https://github.com/pgaskin/dictutil","last_synced_at":"2025-05-01T02:26:09.205Z","repository":{"id":57510949,"uuid":"237811787","full_name":"pgaskin/dictutil","owner":"pgaskin","description":"Tools, documentation, and libraries related to Kobo dictionaries.","archived":false,"fork":false,"pushed_at":"2022-06-02T01:31:16.000Z","size":1044,"stargazers_count":65,"open_issues_count":6,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-30T21:01:46.780Z","etag":null,"topics":["cgo-bindings","command-line-tool","dictionary","documentation","ebooks","go","go-library","golang","kobo"],"latest_commit_sha":null,"homepage":"https://pgaskin.net/dictutil","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pgaskin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-02T17:54:40.000Z","updated_at":"2025-03-12T22:11:47.000Z","dependencies_parsed_at":"2022-09-26T16:31:08.146Z","dependency_job_id":null,"html_url":"https://github.com/pgaskin/dictutil","commit_stats":null,"previous_names":["geek1011/dictutil"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgaskin%2Fdictutil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgaskin%2Fdictutil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgaskin%2Fdictutil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgaskin%2Fdictutil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pgaskin","download_url":"https://codeload.github.com/pgaskin/dictutil/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251811834,"owners_count":21647781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cgo-bindings","command-line-tool","dictionary","documentation","ebooks","go","go-library","golang","kobo"],"created_at":"2024-10-23T12:09:20.581Z","updated_at":"2025-05-01T02:26:09.181Z","avatar_url":"https://github.com/pgaskin.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003edictutil\u003c/h1\u003e\n\n[![](https://img.shields.io/github/v/release/pgaskin/dictutil?include_prereleases)](https://github.com/pgaskin/dictutil/releases) [![](https://img.shields.io/drone/build/pgaskin/dictutil/master)](https://cloud.drone.io/pgaskin/dictutil) [![](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/mod/github.com/pgaskin/dictutil?tab=versions) [![](https://goreportcard.com/badge/github.com/pgaskin/dictutil)](https://goreportcard.com/report/github.com/pgaskin/dictutil)\n\nThis repository contains a collection of tools and libraries to work with Kobo dictionaries, plus comprehensive documentation of Kobo's dictionary format.\n\nUnlike previous attempts at working with Kobo dictionaries, dictutil has full support for all features supported by nickel (word prefixes, unicode, variants, images, etc), with a focus on simplicity, correctness (prefix generation and other features are directly tested against libnickel's code and regexps, v1/v2 dictionaries are differentiated), and completeness (most of the research was done by reverse-engineering libnickel).\n\nDictutil consists of multiple tools and libraries:\n- [**dictutil**](https://pgaskin.net/dictutil/dictutil/) provides commands for installing, removing, unpacking, packing, and performing low-level modifications and tests on Kobo dictionaries. All operations are intended to be correct, lossless, and deterministic.\n- [**dictgen**](https://pgaskin.net/dictutil/dictgen/) simplifies creating full-featured dictionaries for Kobo eReaders, with support for images, unicode prefixes, raw html, markdown, and more.\n- [**dicthtml**](https://pgaskin.net/dictutil/dicthtml/) documents Kobo's dictionary format and how it works.\n- [**examples/gotdict-convert**](https://pgaskin.net/dictutil/examples/gotdict-convert.html) is a working example of using dictutil to convert [GOTDict](https://github.com/wjdp/gotdict) into a Kobo dictionary.\n- [**examples/webster1913-convert**](https://pgaskin.net/dictutil/examples/webster1913-convert.html) is a working example of using dictutil to convert [Project Gutenberg's Webster's Unabridged Dictionary](http://www.gutenberg.org/ebooks/29765.txt.utf-8) into a Kobo dictionary.\n- [**examples/dictzip-decompile**](https://pgaskin.net/dictutil/examples/dictzip-decompile.html) is an **experimental** tool to convert a dictzip into a dictfile.\n- [**examples/bgl-convert**](https://pgaskin.net/dictutil/examples/bgl-convert.html) is a simple tool to convert Babylon BGL dictionaries to a dictfile.\n- *Library:* [**kobodict**](https://pkg.go.dev/github.com/pgaskin/dictutil/kobodict) provides support for reading, writing, encrypting, and decrypting Kobo dictionaries.\n- *Library:* [**dictgen**](https://pkg.go.dev/github.com/pgaskin/dictutil/dictgen) provides the functionality of dictgen as a library.\n- *Library:* [**marisa**](./marisa) provides a simplified self-contained CGO wrapper for [marisa-trie](https://github.com/s-yata/marisa-trie).\n\nDictutil implements [version 2](https://pgaskin.net/dictutil/dicthtml/v1v2.html) of the Kobo dictionary format, which supports firmware versions 4.7.10364+.\n\nFor more information, see the [documentation](https://pgaskin.net/dictutil/). If you just want a quick overview of the utilities provided, continue reading below.\n\n## Download\n- **Documentation** can be found on the [website](https://pgaskin.net/dictutil/).\n- **Tools** (dictutil, dictgen, gotdict-convert, webster1913-convert) can be downloaded from the [releases](https://github.com/pgaskin/dictutil/releases) page.\n- **Pre-built dictionaries** from gotdict-convert and webster1913-convert can be downloaded from [AppVeyor](https://ci.appveyor.com/api/projects/pgaskin/dictutil/artifacts) or from the links below:\n  - GOTDict *(with images, firmware 4.20.14601+)*: [dictzip (dicthtml-gt.zip)](https://ci.appveyor.com/api/projects/pgaskin/dictutil/artifacts/gotdict/dicthtml-gt.zip?branch=master\u0026all=false\u0026pr=false), [source dictfile (gotdict.df)](https://ci.appveyor.com/api/projects/pgaskin/dictutil/artifacts/gotdict/gotdict.df?branch=master\u0026all=false\u0026pr=false)\n  - GOTDict *(without images)*: [dictzip (dicthtml-gt.noimg.zip)](https://ci.appveyor.com/api/projects/pgaskin/dictutil/artifacts/gotdict/dicthtml-gt.noimg.zip?branch=master\u0026all=false\u0026pr=false), [source dictfile (gotdict.noimg.df)](https://ci.appveyor.com/api/projects/pgaskin/dictutil/artifacts/gotdict/gotdict.noimg.df?branch=master\u0026all=false\u0026pr=false)\n  - Webster's 1913 Dictionary: [dictzip (dicthtml-wb.zip)](https://ci.appveyor.com/api/projects/pgaskin/dictutil/artifacts/webster1913/dicthtml-wb.zip?branch=master\u0026all=false\u0026pr=false), [source dictfile (webster1913.df)](https://ci.appveyor.com/api/projects/pgaskin/dictutil/artifacts/webster1913/webster1913.df?branch=master\u0026all=false\u0026pr=false)\n- **API documentation** for the Go libraries can be found on [pkg.go.dev](https://pkg.go.dev/github.com/pgaskin/dictutil).\n\n## Usage\nSee the [documentation](https://pgaskin.net/dictutil/) for more detailed information and examples.\n\n### dictutil\n\n```\nUsage: dictutil command [options] [arguments]\n\nDictutil provides low-level utilities to manipulate Kobo dictionaries (v2).\n\nCommands:\n  install (I)          Install a dictzip file\n  pack (p)             Pack a dictzip file\n  prefix (x)           Calculate the prefix for a word\n  uninstall (U)        Uninstall a dictzip file\n  unpack (u)           Unpack a dictzip file\n  help                 Show help for all commands\n\nOptions:\n  -h, --help   Show this help text\n```\n\n```\nUsage: dictutil install [options] dictzip\n\nOptions:\n  -k, --kobo string         KOBOeReader path (default: automatically detected)\n  -l, --locale string       Locale name to use (format: ALPHANUMERIC{2}[-ALPHANUMERIC{2}]) (default: detected from filename if in format dicthtml-**.zip)\n  -n, --name string         Custom additional label for dictionary (ignored when replacing built-in dictionaries) (doesn't have any effect on 4.20.14601+)\n  -b, --builtin string      How to handle built-in locales [replace = replace and prevent from syncing] [ignore = replace and leave syncing as-is] (doesn't have any effect on 4.24.15672+) (default \"replace\")\n  -B, --no-custom           Whether to force installation to .kobo/dict instead of .kobo/custom-dict (4.24.15672+ only)\n      --use-extra-locales   Whether to use ExtraLocales on 4.24.15672+ if not a built-in dictionary (this is not required anymore since 4.24.15672) (4.24.15672+ only)\n  -h, --help                Show this help text\n\nNote:\n  If you are not replacing a built-in dictionary and are using a firmware\n  version before 4.24.15672, the 'Enable searches on extra dictionaries patch'\n  must be installed or you will not be able to select your custom dictionary.\n```\n\n```\nUsage: dictutil uninstall [options] locale\n\nOptions:\n  -k, --kobo string      KOBOeReader path (default: automatically detected)\n  -b, --builtin string   How to handle built-in locales [normal = uninstall the same way as the UI] [delete = completely delete the entry (doesn't have any effect on 4.20.14601+)] [restore = download the original dictionary from Kobo again] (doesn't have any effect on 4.24.15672+) (default \"normal\")\n  -B, --no-custom        Uninstall built-in dictionaries instead of custom ones on 4.24.15672+\n  -h, --help             Show this help text\n```\n\n```\nUsage: dictutil pack [options] dictdir\n\nOptions:\n  -o, --output string   The output dictzip filename (will be overwritten if it exists) (default \"dicthtml.zip\")\n  -c, --crypt string    Encrypt the dictzip using the specified encryption method (format: method:keyhex)\n  -h, --help            Show this help text\n```\n\n```\nUsage: dictutil unpack [options] dictzip\n\nOptions:\n  -o, --output string   The output directory (must not exist) (default: the basename of the input without the extension)\n  -c, --crypt string    Decrypt the dictzip (if needed) using the specified encryption method (format: method:keyhex)\n  -h, --help            Show this help text\n```\n\n```\nUsage: dictutil prefix [options] word...\n\nOptions:\n  -f, --format string   The output format (go-slice, go-map, csv, tsv, json-array, json-object) (default \"json-array\")\n  -h, --help            Show this help text\n```\n\n### dictgen\n\n```\nUsage: dictgen [options] dictfile...\n\nOptions:\n  -o, --output string         The output filename (will be overwritten if it exists) (- is stdout) (default \"dicthtml.zip\")\n  -c, --crypt string          Encrypt the dictzip using the specified encryption method (format: method:keyhex)\n  -I, --image-method string   How to handle images (if an image path is relative, it is loaded from the current dir) (base64 - optimize and encode as base64, embed - add to dictzip, remove) (default \"base64\")\n      --remove-footer         Add code to prevent the non-applicable dictionary source footer for certain locales from being added after the entry (e.g. if replacing the French dictionary)\n  -h, --help                  Show this help text\n\nIf multiple dictfiles (*.df) are provided, they will be merged (duplicate entries are fine; they will be shown in sequential order). To read from stdin, use - as the filename.\n\nNote that the only usable image method is currently removing them or using base64-encoding (for firmware 4.20.14601+; older versions segfault in the in-book dictionary), as embedded dict:/// image URLs cause the webviews to appear blank (this is a nickel bug). See https://github.com/pgaskin/dictutil/issues/1 for more details.\n\nSee https://pgaskin.net/dictutil/dictgen for more information about the dictfile format.\n```\n\n**See [here](https://pgaskin.net/dictutil/dictgen/) for information and examples of the dictfile format.**\n\n### gotdict-convert\n\n```\nUsage: gotdict-convert [options]\n\nOptions:\n  -g, --gotdict string   The path to the local copy of github.com/wjdp/gotdict. (default \"./gotdict\")\n  -o, --output string    The output filename (will be overwritten if it exists) (- is stdout) (default \"./gotdict.df\")\n  -I, --images           Include images in dictfile\n  -h, --help             Show this help text\n\nTo convert the resulting dictfile into a dictzip, use dictgen.\n```\n\n### webster1913-convert\n\n```\nUsage: webster1913-convert [options] gutenberg_webster1913_path\n\nOptions:\n  -o, --output string   The output filename (will be overwritten if it exists) (- is stdout) (default \"./webster1913.df\")\n      --dump            Instead of converting, dump the parsed dictionary to stdout as JSON (for debugging)\n  -h, --help            Show this help text\n\nArguments:\n  gutenberg_webster1913_path is the path to Project Gutenberg's Webster's 1913 dictionary. Use - to read from stdin.\n\nTo convert the resulting dictfile into a dictzip, use dictgen.\n```\n\nThe original dictionary can be downloaded [here](http://www.gutenberg.org/ebooks/29765.txt.utf-8) or [here](https://github.com/pgaskin/dictserver/raw/master/data/dictionary.txt).\n\n### dictzip-decompile\n\n```\nUsage: dictzip-decompile [options] dictzip\n\nOptions:\n  -o, --output string   The output filename (will be overwritten if it exists) (- is stdout) (default \"./decompiled.df\")\n  -r, --resources       Also extract referenced resources to the current directory (warning: any existing files will be overwritten, so it is recommended to run in an empty directory if enabled)\n  -h, --help            Show this help text\n\nArguments:\n  dictzip is the path to the dictzip to decompile.\n\nTo convert the resulting dictfile into a dictzip, use dictgen.\n\nNote: The regenerated dictzip from the dictfile may not match exactly, but it will look the same, and certain bugs with prefixes and variants will be implicitly fixed by the conversion process (i.e. variant in wrong file, incorrect prefix, missing words in index file). All output is in raw HTML, not Markdown.\n\nThis is an experimental tool, and the output may not be perfect on complex dictionaries.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgaskin%2Fdictutil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpgaskin%2Fdictutil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgaskin%2Fdictutil/lists"}