opencc4j

Opencc4j provides several utility classes for different Chinese character conversion needs. All utility classes follow a consistent API design for easy memorization.

Core utility classes:

• ZhConverterUtil: Basic Simplified/Traditional Chinese conversion.
• ZhTwConverterUtil: Conversion between Mainland Chinese and Taiwan regions.
• ZhHkConverterUtil: Conversion between Mainland Chinese and Hong Kong regions.
• ZhJpConverterUtil: Conversion between Mainland Chinese and Japanese Shinjitai (new character forms).

To use Opencc4j in your Java project, add the following dependency to your pom.xml file:

<dependency>
    <groupId>com.github.houbb</groupId>
    <artifactId>opencc4j</artifactId>
    <version>1.14.0</version>
</dependency>

Starting from version 1.1.0, you can use the ZhConvertBootstrap class to integrate your custom Segment implementation. ZhConvertBootstrap supports a fluent API, making it easy to chain segmentation and conversion tasks.

// Assuming MySegment is your custom implementation
final String result = ZhConvertBootstrap.newInstance()
    .segment(new MySegment())
    .toTraditional(original);

Opencc4j uses a bootstrap pattern to configure segmentation (tokenization) and data maps. This is useful if you want to change how words are split or use specific regional data.

Default Configuration:

ZhConvertBootstrap.newInstance()
                .segment(Segments.defaults())
                .dataMap(DataMaps.defaults())
                .init();

Taiwan Configuration:

ZhConvertBootstrap.newInstance()
                .segment(Segments.twFastForward())
                .dataMap(DataMaps.taiwan())
                .init();

ZhConvertBootstrap.newInstance()
                .segment(Segments.defaults())
                .dataMap(DataMaps.defaults()).init();

Use ZhConverterUtil for standard Simplified and Traditional Chinese conversions.

To Simplified:

String original = "生命不息，奮鬥不止";
String result = ZhConverterUtil.toSimple(original);
// result: "生命不息，奋斗不止"

To Traditional:

String original = "生命不息，奋斗不止";
String result = ZhConverterUtil.toTraditional(original);
// result: "生命不息，奮鬥不止"

String original = "生命不息，奮鬥不止";
String result = ZhConverterUtil.toSimple(original);
Assert.assertEquals("生命不息，奋斗不止", result);

When a single character has multiple possible mappings, these methods return them as a list.

To Traditional list:

// Returns [幹, 乾, 干]
List<String> result = ZhConverterUtil.toTraditional('干');

To Simplified list:

// Returns [测]
List<String> result = ZhConverterUtil.toSimple('測');

Assert.assertEquals("[幹, 乾, 干]", ZhConverterUtil.toTraditional('干').toString());

Use specialized utilities for regional conversions:

Taiwan (ZhTwConverterUtil):

ZhTwConverterUtil.toTraditional("使用互联网"); // "使用網際網路"
ZhTwConverterUtil.toSimple("使用網際網路"); // "使用互联网"

Hong Kong (ZhHkConverterUtil):

ZhHkConverterUtil.toTraditional("千家万户"); // "千家萬户"
ZhHkConverterUtil.toSimple("千家萬户"); // "千家万户"

Japan (ZhJpConverterUtil): Converts via the path: Simplified $\rightarrow$ Standard Traditional $\rightarrow$ Japanese Shinjitai.

ZhJpConverterUtil.toTraditional("我在日本学习音乐"); // "我在日本学習音楽"
ZhJpConverterUtil.toSimple("我在日本学習音楽"); // "我在日本学习音乐"

You can retrieve a list of words/characters identified as Simplified or Traditional within a string. This uses the configured segmentation (tokenization) strategy.

Get Simplified list:

final String original = "生命不息奋斗不止";
final List<String> resultList = ZhConverterUtil.simpleList(original);
// result: [生, 命, 不, 息, 奋斗, 不, 止]

Get Traditional list:

final String original = "生命不息奮鬥不止";
final List<String> resultList = ZhConverterUtil.traditionalList(original);
// result: [生, 命, 不, 息, 奮, 鬥, 不, 止]

final String original = "生命不息奋斗不止";
final List<String> resultList = ZhConverterUtil.simpleList(original);
Assert.assertEquals("[生, 命, 不, 息, 奋斗, 不, 止]", resultList.toString());

You can implement your own segmentation logic by implementing the Segment interface. This allows you to integrate custom tokenizers into the Opencc4j conversion pipeline.

public interface Segment {
    /**
     * Segment the original text
     * @param original The original string
     * @return A list of segmented strings
     */
    List<String> seg(final String original);
}

The ZhConverterUtil class provides methods to check the character type of strings or individual characters.

Check if Simplified:

• isSimple(String): Returns true if the entire string is Simplified.
• isSimple(char): Returns true if the character is Simplified.
• containsSimple(String): Returns true if the string contains any Simplified characters.

Check if Traditional:

• isTraditional(String): Returns true if the entire string is Traditional.
• isTraditional(char): Returns true if the character is Traditional.
• containsTraditional(String): Returns true if the string contains any Traditional characters.

Check if Chinese:

• isChinese(String): Returns true if the entire string is Chinese.
• isChinese(char): Returns true if the character is Chinese.
• containsChinese(char): Returns true if the string contains Chinese characters.

If the default segmentation methods do not suit your specific business logic, you can implement the Segment interface to provide your own segmentation implementation. This allows you to control how text is split before conversion.

import com.github.houbb.opencc4j.support.segment.Segment;
import java.util.List;

/**
 * Implement this interface to provide custom segmentation logic.
 */
public class MySegment implements Segment {

    @Override
    public List<String> seg(final String original) {
        // Your custom segmentation logic here
        return // ... list of segmented strings;
    }
}