sensitive-word: a high-performance DFA sensitive-word filter for Java

What sensitive-word does

Filtering sensitive, banned or dirty words out of user text is a recurring need for Chinese-language applications, from forums to chat to user profiles. sensitive-word is a Java library built for exactly that, using a deterministic finite automaton, a DFA, to detect and filter such words at high speed. Beyond plain detection it adds features that matter in Chinese text: word tag classification and grading, conversion between traditional and simplified characters, full-width and half-width normalization, Chinese-to-pinyin conversion, and fuzzy search. It comes with bundled dictionaries so it works out of the box. The audience is Java developers who need content filtering and want a ready, fast component rather than assembling their own matcher and word lists. It is a library you embed in a JVM application, aimed squarely at the practical problem of scanning text for prohibited terms.

DFA matching with Chinese-aware normalization

The mechanism is a DFA over a trie of the dictionary words, which is why it is fast: scanning input text against a DFA runs in time proportional to the text length regardless of how many words are in the dictionary, avoiding the cost of checking each word separately. On top of that core, the library normalizes text so evasion is harder: it converts traditional characters to simplified and full-width to half-width before matching, folds case, and can match through inserted symbols, so a word disguised with spacing or variants is still caught. The pinyin conversion and fuzzy search extend detection to phonetic and approximate forms. The word-tagging system lets you classify and grade matches rather than treat all hits alike, which is useful when different categories of word warrant different handling. The result is a matcher tuned to how prohibited words actually appear in Chinese text.

Adding it through Maven

sensitive-word is published to Maven Central, so you add it as a dependency in your build. The README gives the coordinate:

<dependency>
    <groupId>com.github.houbb</groupId>
    <artifactId>sensitive-word</artifactId>
    <version>0.29.5</version>
</dependency>

It requires Maven 3.x or newer and a JVM. With the dependency in place, you use the library's bootstrap entry point to check whether text contains a sensitive word, find the matches, or replace them, drawing on the bundled dictionaries by default. The first real use is running a sample string that contains a known dictionary word through the detection call to confirm it is flagged, and through the replacement call to see it masked, which verifies the setup and the default dictionary before you add custom words or tune the normalization and tagging options for your application.

Where a filter library has limits

The limitations are those of any word-list filter. Detection is only as good as the dictionary: new slang, deliberate obfuscation beyond what normalization catches, and context-dependent meaning will slip past a list-based matcher, so it reduces prohibited content rather than guaranteeing none, and it needs dictionary maintenance over time. It is Chinese-focused in its normalization and bundled data, so it fits that use best and would need different data for other languages. It is a JVM library, so it serves Java applications and not other stacks directly. And a purely lexical filter cannot judge intent, so it will both miss cleverly disguised words and flag innocent text that happens to contain a listed substring, which is why the tagging and grading exist to let you tune responses. These are inherent to lexical filtering, not defects of this implementation.

sensitive-word versus building your own or a cloud API

Two alternatives bracket it. Building your own trie or DFA matcher gives you full control and no dependency, but you then own the algorithm, the normalization edge cases and, hardest of all, the word dictionaries, which is substantial work this library has already done. A cloud content-moderation API goes the other way: it can apply machine-learning models that understand context and images, potentially catching what a word list misses, but it sends your text to a third party, costs money per call, and adds latency and a network dependency. sensitive-word sits in between as a fast, self-contained, in-process filter with ready dictionaries and Chinese-aware normalization. Choose a cloud API when contextual, multimodal moderation justifies the cost and data sharing; build your own only for unusual needs; and reach for sensitive-word when you want a proven local filter for Chinese text embedded directly in a Java service.

Apache-2.0 and maintenance

sensitive-word is Apache-2.0 licensed, a permissive license that suits embedding it in commercial Java applications, and it is distributed through Maven Central with documentation on the author's site. The last push was on 2026-03-23, and the project has a long history with released dictionary assets and format-normalization work, such as unifying case, converting full-width to half-width and traditional to simplified, and de-duplicating the word lists. Because its effectiveness rests on its dictionaries, treat the word data as something to review and extend for your domain rather than trust wholesale, and expect to add custom words for terms specific to your application. Adopt it when you need fast, local sensitive-word filtering for Chinese text in a JVM service, pull it from Maven, verify detection on known terms, and configure tags and custom words to fit your policy.

Editorial conclusion

Adopt sensitive-word if you build Java applications that must filter sensitive or banned words in Chinese text and want a fast, self-contained DFA filter with bundled dictionaries, tagging, pinyin and normalization. Do not expect it to understand context or catch every disguised term, since it is a lexical filter that needs dictionary upkeep, and it is Chinese-focused and JVM-only. Add it through Maven as com.github.houbb:sensitive-word, verify detection and replacement on known terms, and add custom words and tags to match your policy.

Frequently asked questions

Official sources

1. houbb/sensitive-word on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases