gocc

package module
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

README

gocc

Build Status Lint Status Go Reference

简体中文 | 繁體中文 | 日本語

Package gocc is a Go implementation of OpenCC (Open Chinese Convert 開放中文轉換): conversion between Traditional Chinese, Simplified Chinese and regional variants.

It follows the OpenCC 1.4 conversion model and ships its configs and dictionaries, stored in cedar double-array tries.

Install

go get github.com/go-ego/gocc
go install github.com/go-ego/gocc/cmd/gocc@latest

Usage

package main

import (
	"fmt"

	"github.com/go-ego/gocc"
)

func main() {
	s2t, err := gocc.New("s2t")
	if err != nil {
		panic(err)
	}
	fmt.Println(s2t.Convert("那里湖面总是澄清, 那里空气充满宁静"))
	// 那裏湖面總是澄清, 那裏空氣充滿寧靜

	fmt.Println(gocc.MustNew("s2twp").Convert("鼠标和内存"))
	// 滑鼠和記憶體
}

Custom config (OpenCC JSON; X.ocd2/X.ocd dictionaries are read as X.txt):

c, err := gocc.NewFromConfig(configJSON, os.DirFS("dicts"))

Config file, like OpenCC's SimpleConverter: dictionaries are searched in the config's directory, then LoadDict directories, then the built-in ones:

c, err := gocc.NewFromFile("my/s2t_custom.json")

Dictionary directory, like OpenCC's --path or gse's LoadDict: files found there replace the built-in dictionaries of the same name:

c, err := gocc.New("s2t", gocc.LoadDict("my/dicts")) // e.g. my/dicts/STPhrases.txt

Build with -tags ne to leave the dictionaries (~1.5 MB) out of the binary, like gse; the configs stay embedded, so load the dictionaries with LoadDict:

go build -tags ne ./cmd/gocc && gocc -c s2t -path /usr/share/gocc/dictionary

Simplified(), Traditional() and JP() report the converter's output, read from its config name: t2s is Simplified, s2twp Traditional, t2jp JP.

Configs may contain comments and trailing commas, as OpenCC allows.

gocc.WithTofuRisk() also uses dictionaries marked may_output_tofu, whose rare characters common fonts may not render (OpenCC's --include-tofu-risk-dictionaries).

Command line:

echo "不能踏入同一条河流" | gocc -c s2t
# 不能踏入同一條河流
gocc -c t2s -i in.txt -o out.txt
gocc -c my/config.json -path my/dicts  # config file and dictionary directory

Behaviour on unusual input: invalid UTF-8 bytes and NUL bytes pass through unchanged (OpenCC throws on invalid UTF-8). AppendConvert's dst must not overlap its input.

Conversions

Name Conversion
s2t Simplified Chinese to Traditional Chinese
t2s Traditional Chinese to Simplified Chinese
s2tw Simplified Chinese to Traditional Chinese (Taiwan Standard)
tw2s Traditional Chinese (Taiwan Standard) to Simplified Chinese
s2hk Simplified Chinese to Traditional Chinese (Hong Kong variant)
hk2s Traditional Chinese (Hong Kong variant) to Simplified Chinese
s2twp Simplified Chinese to Traditional Chinese (Taiwan Standard) with Taiwanese idiom
tw2sp Traditional Chinese (Taiwan Standard) to Simplified Chinese with Mainland idiom
s2hkp Simplified Chinese to Traditional Chinese (Hong Kong variant) with Hong Kong idiom
hk2sp Traditional Chinese (Hong Kong variant) to Simplified Chinese with Mainland idiom
t2tw Traditional Chinese (OpenCC Standard) to Taiwan Standard
tw2t Traditional Chinese (Taiwan Standard) to Traditional Chinese (OpenCC Standard)
t2hk Traditional Chinese (OpenCC Standard) to Hong Kong variant
hk2t Traditional Chinese (Hong Kong variant) to Traditional Chinese (OpenCC Standard)
t2jp Traditional Chinese characters (Kyūjitai) to New Japanese Kanji (Shinjitai)
jp2t New Japanese Kanji (Shinjitai) to Traditional Chinese characters (Kyūjitai)
s2seal, t2seal, seal2t Seal script conversions

Updating the data

data/ holds OpenCC's data/config/*.json and data/dictionary/*.txt plus the dictionaries OpenCC generates at build time (*Rev.txt, TSCharactersExt.txt, STPhrases_GeneratedFromRegionalPhrases.txt):

go run ./internal/cmd/gendict -opencc /path/to/OpenCC   # sync and regenerate
go generate                                              # regenerate only

Lint

The code is checked by golangci-lint v2 in CI, with the config in .golangci.yml:

go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
golangci-lint run ./...
golangci-lint run --build-tags ne ./...

License

Apache-2.0. The dictionaries and configs come from OpenCC (Apache-2.0).

Documentation

Overview

Package gocc is a Go implementation of OpenCC (Open Chinese Convert), converting between Traditional Chinese, Simplified Chinese and regional variants (Taiwan, Hong Kong, Japanese Shinjitai, seal script).

It follows the OpenCC 1.4 conversion model: normalization, optional maximum-match segmentation, and a chain of dictionary conversions whose groups match with "short_circuit" or "union" policy. The OpenCC configs and dictionaries are embedded (build with -tags ne to leave the dictionaries out and use LoadDict); dictionaries are stored in cedar double-array tries and shared between converters.

Example
package main

import (
	"fmt"

	gocc "github.com/go-ego/gocc"
)

func main() {
	s2t, err := gocc.New("s2t")
	if err != nil {
		panic(err)
	}
	fmt.Println(s2t.Convert("自然语言处理是人工智能领域中的一个重要方向。"))

	tw := gocc.MustNew("s2twp")
	fmt.Println(tw.Convert("鼠标和内存"))
}
Output:
自然語言處理是人工智能領域中的一個重要方向。
滑鼠和記憶體

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Conversions

func Conversions() []string

Conversions lists the built-in configurations, such as "s2t" and "tw2sp".

Types

type Converter

type Converter struct {
	// contains filtered or unexported fields
}

Converter converts text with one OpenCC configuration. It is safe for concurrent use.

func MustNew

func MustNew(conversion string, opts ...Option) *Converter

MustNew is like New but panics on error.

func New

func New(conversion string, opts ...Option) (*Converter, error)

New returns the converter of a built-in configuration such as "s2t" (Simplified to Traditional) or "t2s"; see Conversions. A ".json" suffix is accepted.

func NewFromConfig

func NewFromConfig(config []byte, dicts fs.FS, opts ...Option) (*Converter, error)

NewFromConfig builds a converter from an OpenCC JSON config whose dictionary files are read from dicts. Text dictionaries are used for every dictionary type: "X.ocd2" and "X.ocd" are read as "X.txt". The LoadDict directories are searched after dicts.

func NewFromFile

func NewFromFile(config string, opts ...Option) (*Converter, error)

NewFromFile builds a converter from an OpenCC JSON config file, like OpenCC's SimpleConverter. As in OpenCC, dictionary files are searched in the config's directory, then the LoadDict directories, then among the built-in dictionaries.

func (*Converter) AppendConvert

func (c *Converter) AppendConvert(dst, s []byte) []byte

AppendConvert appends the conversion of s to dst and returns the result. dst must not overlap s.

func (*Converter) Convert

func (c *Converter) Convert(s string) string

Convert converts s.

func (*Converter) JP

func (c *Converter) JP() bool

JP reports whether the converter outputs Japanese Kanji, as "t2jp" (Shinjitai) and "jp2t" (Kyūjitai) do.

func (*Converter) Name

func (c *Converter) Name() string

Name returns the configuration name, e.g. "Simplified Chinese to Traditional Chinese (OpenCC Standard)".

func (*Converter) Simplified

func (c *Converter) Simplified() bool

Simplified reports whether the converter outputs Simplified Chinese, as "t2s" and "tw2sp" do. Like Traditional and JP, it reads the target from the config name, "... to Simplified Chinese ...".

func (*Converter) Traditional

func (c *Converter) Traditional() bool

Traditional reports whether the converter outputs Traditional Chinese, as "s2t", "s2twp" and "seal2t" do.

type Option

type Option func(*options)

Option configures a Converter.

func LoadDict

func LoadDict(dir string) Option

LoadDict searches dir for dictionary files before the built-in dictionaries, like OpenCC's --path or gse's LoadDict. A file found in dir replaces the built-in one of the same name. Later paths are searched after earlier ones.

func WithTofuRisk

func WithTofuRisk() Option

WithTofuRisk includes dictionaries marked "may_output_tofu": rare characters that common fonts may not render (OpenCC's --include-tofu-risk-dictionaries).

Directories

Path Synopsis
cmd
gocc command
Command gocc converts Chinese text between Traditional, Simplified and regional variants, like the opencc command.
Command gocc converts Chinese text between Traditional, Simplified and regional variants, like the opencc command.
internal
cmd/gendict command
Command gendict refreshes the embedded OpenCC data: it optionally syncs configs and source dictionaries from an OpenCC checkout, then writes the generated dictionaries into data/dictionary.
Command gendict refreshes the embedded OpenCC data: it optionally syncs configs and source dictionaries from an OpenCC checkout, then writes the generated dictionaries into data/dictionary.
dictfile
Package dictfile reads and writes OpenCC text dictionaries.
Package dictfile reads and writes OpenCC text dictionaries.
dictgen
Package dictgen derives the generated OpenCC dictionaries from their sources, mirroring the scripts in OpenCC's data/scripts directory.
Package dictgen derives the generated OpenCC dictionaries from their sources, mirroring the scripts in OpenCC's data/scripts directory.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL