Custom Dictionary Documentation

Hello Pleco Team!

I'm trying to build a custom dictionary for Pleco, but I am having trouble locating the documentation. The only thing I've found is this page, which isn't very verbose.
So far, the only thing I know is that I can have a text file with this syntax:

And it will make an entry where the headword is 字, the PY is zì (this will cause 字 to show in 4th tone's colour) and the definition contains two lines, "definition1" and "definition2".
I've also seen that prepending @ to the PY will make it not be coloured.

That's about it. I haven't found how to do the following:
  • number definitions, as found in PLC dictionary
  • create headings (e.g. "NOUN")
  • create links to other entries (e.g. some character in the def appears in blue and is clickable)
  • indicate simplified / traditional (or generally "variants")
  • examples
  • any other sort of available mark-up
Does Pleco follow a standard syntax? Is it documented somewhere and I just haven't found it?
Would it be possible to make e.g. CC-CEdict exportable, for learning purposes? After all, it's under CC and is freely available elsewhere, so it probably doesn't need the same sort of protection as e.g. Grand Ricci.

Thanks in advance.
Last edited:
Hi vermillon,

I can answer a few of your questions.

On Simplified/Traditional: To indicate to Pleco whether a Hanzi expression is in Simplified or Traditional, you write it in Simplified characters first and then, without spaces, the Traditional character expression in square brackets after it. So it's:


There are a few unofficial markup options for version 3.2, including color, but these will definitely be modernized with version 4.0, so it might be a bit of a wasted effort to encode everything in this format right now: (unless there is going to be some compatibility mode or conversion function in Pleco 4.0)

Hope this helps,



Staff member
Yeah, the user dictionary format at the moment isn't really intended to support any of those features, unfortunately - it's just for basic flat text, you can hack it into doing some simple formatting as @Shun says but that's about it.

For future planning purposes, the new format in 4.0 will be a dialect of Markdown, so as far as numbers and generic rich text that pretty much tells you how that will work. (it will NOT support inline HTML, though, only markdown tags) We haven't finalized the format we'll use for 'tag' formatting like NOUN VERB etc, or for links - they will be supported, we're just reluctant to commit to a format until the last possible minute since then we're kind of stuck with it for a while :)

Embedded examples will be handled by embedded links (i.e. you'll create another 'entry' of type 'example' and then link to that from the main entry) - in an import file the current plan is that you'll bracket off an example in some way so the importer can then know to pull that out of the import line, create an example entry from it and link to that, but that may still be revised. The offset / quote bar formatting for examples will just be a Markdown quote, though, so if you didn't care about your example being treated as such semantically (getting tone coloring and a TTS button and so forth) and just wanted it to look like ours do you could compose it in pure markdown using that.
Well, Shun, Mike, thanks a lot for the answer! The guide you've linked is definitely enough to let me improve what I've already built. It's not a lot of code, so it's fine if I have to re-do some of it when the new format becomes available, especially if it means I can build something really pretty :)

I'm sure the question gets asked every other day, but is there a very rough estimate of when 4.0 is coming? (I see posts mentioning it in mid-2017, but the tone of recent posts suggests that perhaps it's not that far anymore?). This year?
Last edited:


Staff member
I'm sure the question gets asked every other day, but is there a very rough estimate of when 4.0 is coming? (I see posts mentioning it in mid-2017, but the tone of recent posts suggests that perhaps it's not that far anymore?). This year?
Hopefully, at least in beta form. But we've missed enough release dates that that's certainly not a promise and it could well take until next year.

We were really hoping for more clarity from Apple about where they were going with the iOS-on-Mac "Project Catalyst" but it's turned out that the crappy half-finished version of that they shipped in beta in June was in fact the real thing and it seemingly won't be turned into anything more than that until next summer, so we're now trying to work up a sort of 'transitional UI' to take us from whenever-4.0-launches through to fall of 2020 when we'll hopefully be able to launch something that's more nicely desktop-optimized. (this is not to say we won't ship a Catalyst app before then, only that it'll probably be a pretty ugly vanilla one - not something we'll have taken a lot of time optimizing)

We're also still finalizing the designs of a few things we're going to be stuck with long-term once we launch them, like the aforementioned Markdown formatting tags, some high-level search configuration stuff (e.g. a more flexible version of "filtering" to replace our current nihao#hello syntax), a unified system for customizing command bars and toolbars and dispatching commands to them, etc.
Any chance some of these features could make it into a 3.3 release instead? I imagine it could help alleviate the amount of feedback to deal with once 4.0 is out, especially if 4.0 means everything changes.
Of course, your development resources are limited, but "release early, release often" as they say :)


Staff member
No, it’s pretty much a total fork - we diverged from the 3.x base a couple of years ago, about the only stuff we can back port is standalone functionality like the OCR motion detection system (our “new OCR” feature).


Staff member
(I should also add since this is an Android thread that the aforementioned timeline was for iOS - our engine is written in cross platform native code and that’s way, way easier to test / debug on iOS, so the Android port probably won’t happen until after 4.0 final is out on iOS)