gomanize

README

Gomanize

A Go library and CLI that romanizes Devanagari (Hindi) into readable Latin script, built for song lyrics and other colloquial text. Rule-based engine with optional embedded learned components; no runtime dependencies.

नमस्ते दुनिया  →  namaste duniya

Try it in your browser → budhash.com/gomanize — the full engine, compiled to WebAssembly, runs entirely client-side (no server; no text leaves your machine).

Use it from JavaScript/TypeScript → @budhash/gomanize on npm — the same engine as a WebAssembly package for Node and the browser (not a reimplementation, so output is byte-identical to the CLI).

It does romanization — spelling Hindi the way it sounds (नमस्ते → namaste) — not the strict, reversible transliteration of IAST or ISO 15919. There is no single correct answer (जनता is validly janata, janta, or janataa), so it is measured against all human-attested variants; on verse, its error rate is at the level where human romanizers disagree. Background, methodology, and limitations: docs/RESEARCH.md.

Install

# CLI via Homebrew (macOS/Linux)
brew install budhash/tools/gomanize

# Go library
go get github.com/budhash/gomanize

# JavaScript/TypeScript (Node or browser) — the same engine as WebAssembly
npm install @budhash/gomanize

# CLI from source
git clone https://github.com/budhash/gomanize
cd gomanize
make build

Prebuilt binaries for Linux/macOS/Windows (amd64+arm64) are also attached to each GitHub release.

Usage

CLI

./gomanize "नमस्ते दुनिया"       # namaste duniya
echo "हिंदी गाना" | ./gomanize   # hindi gana

Flag	Effect	Example
(default)	Colloquial rules	जनता → janta
--keep-medial-schwa	Retain medial schwa	जनता → janata
--long-vowels	aa for every ā	गाना → gaanaa
--simple-nasals	Simplified nasal endings	करें → karen
--schwa-model	Learned schwa classifier	जनता → janta
--lexicon	Attested spellings for 8,367 known words	अंकल → uncle
--rerank	Character-LM picks best of rules/schwa-model outputs	see Accuracy below
--list-rules, --debug	Inspect and trace the rule engine

Library (Go)

import gomanize "github.com/budhash/gomanize"

g, err := gomanize.New("hindi")
if err != nil {
    panic(err)
}
fmt.Println(g.Translit("नमस्ते दुनिया")) // "namaste duniya"

Options mirror the CLI flags via gomanize.NewWithOptions.

Library (JavaScript/TypeScript)

The @budhash/gomanize package is the same engine compiled to WebAssembly — not a reimplementation, so output is byte-identical to the Go CLI. Works in Node and the browser:

import { load } from "@budhash/gomanize";

const g = await load();
g.translit("नमस्ते दुनिया");              // "namaste duniya"
g.translit("गाना", { longVowels: true }); // "gaanaa"

The same flags are accepted as options (longVowels, simpleNasals, keepMedialSchwa, schwaModel, lexicon, rerank).

Accuracy

Scored against all human-attested romanization variants (see docs/RESEARCH.md for methodology, datasets, and the full result set including negative results):

Benchmark	Result
Curated Dakshina	86.2% exact / 92.9% any attested variant (94.8% with --rerank)
Naturally-typed Hindi (COMI-LINGUA), token-weighted	79.9% (86.6% with --lexicon)
Held-out unseen words	69.3% (70.7% with --rerank)
Song lyrics, line-level character error	0.049, or 0.039 with --lexicon (human agreement floor is about 0.054)

Known limitations (vowel-length spelling, named entities, cross-convention scoring): docs/RESEARCH.md §4.

Documentation

Document	Contents
CHANGELOG.md	Release history and notable changes
docs/RESEARCH.md	The problem, literature, datasets and licenses, evaluation methodology, all results including negatives
docs/DESIGN.md	Engine architecture, rule system, character mappings, learned components, future directions
docs/ROADMAP.md	Post-1.0 directions (convention schemes, more languages) with tradeoffs
web/README.md	The browser demo (budhash.com/gomanize): make wasm / make wasm-serve and the Pages deploy
CLAUDE.md	Development workflow, commands, repository conventions
docs/PROCESS.md	Task tracking, PR discipline, accuracy reporting rules
docs/reviews/	Dated decision records for every result, including failures

Development

make init     # First-time setup (deps + pre-commit hooks)
make ci       # Full pipeline: format check, lint, build, tests, benchmarks
make help     # All commands

Contributions follow docs/PROCESS.md: feature branches, make ci before PRs, accuracy changes must show before/after on the benchmark suite.

License

MIT. Copyright (c) 2023-2026 Budhaditya (budhash@gmail.com).

Benchmark data derives from Dakshina (CC BY-SA 4.0), Aksharantar (CC-BY 4.0), COMI-LINGUA (CC-BY 4.0), and Shabd (CC0); see docs/RESEARCH.md for full attribution.

Documentation

Overview

Package gomanize transliterates Devanagari (Hindi) text into readable Latin script, using a rule-based engine with optional embedded learned components (a schwa classifier, an attested-spelling lexicon, and a character-LM re-ranker). It targets colloquial, diacritic-free romanization of the kind used for song lyrics.

Basic use:

g, err := gomanize.New("hindi")
out := g.Translit("नमस्ते दुनिया") // "namaste duniya"

A Gomanize instance is safe for concurrent Translit calls. TranslitDebug and runtime rule toggling (DisableRule/EnableRule) mutate engine state and must not run concurrently with other calls on the same instance. TranslitDebug returns nil debug info when the Lexicon or Rerank options short-circuit the rule pipeline.

Index

• Variables
• type DebugInfo
• type EngineOption
• type ExtendedRomanizer
• type Gomanize
  • func New(language string) (*Gomanize, error)
  • func NewWithOptions(language string, opts Options, engineOpts ...EngineOption) (*Gomanize, error)
  • func (g *Gomanize) DisableRule(pattern string) int
  • func (g *Gomanize) EnableRule(pattern string) int
  • func (g *Gomanize) GetOptions() Options
  • func (g *Gomanize) ListRules(pattern string) []RuleStatus
  • func (g *Gomanize) SetOptions(opts Options)
  • func (g Gomanize) Test()
  • func (g Gomanize) Translit(sentence string) string
  • func (g Gomanize) TranslitDebug(word string) (string, *DebugInfo)
• type Options
  • func NewOptions() Options
• type Romanizer
• type RuleStatus

Variables

var WithDisabledRules = core.WithDisabledRules

WithDisabledRules returns an option that disables rules matching the given patterns. Patterns can be exact names or glob patterns (e.g., "schwa.*", "vowel.long-aa.*").

var WithEnabledRules = core.WithEnabledRules

WithEnabledRules returns an option that enables rules matching the given patterns. Useful for enabling rules that are disabled by default.

Types

type DebugInfo

type DebugInfo = core.DebugInfo

DebugInfo contains debugging information from transliteration.

type EngineOption

type EngineOption = core.EngineOption

EngineOption configures engine creation.

type ExtendedRomanizer

type ExtendedRomanizer interface {
	Romanizer
	// ListRules returns all rules with their enabled/disabled status.
	// If pattern is empty, returns all rules.
	ListRules(pattern string) []RuleStatus
	// DisableRule disables rules matching the given pattern.
	DisableRule(pattern string) int
	// EnableRule enables rules matching the given pattern.
	EnableRule(pattern string) int
}

ExtendedRomanizer extends Romanizer with rule management capabilities.

type Gomanize

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

func New

func New(language string) (*Gomanize, error)

New creates a Gomanize instance with default options.

func NewWithOptions

func NewWithOptions(language string, opts Options, engineOpts ...EngineOption) (*Gomanize, error)

NewWithOptions creates a Gomanize instance with custom options.

func (*Gomanize) DisableRule

func (g *Gomanize) DisableRule(pattern string) int

DisableRule disables rules matching the given pattern. Returns the number of rules disabled, or 0 if not supported.

func (*Gomanize) EnableRule

func (g *Gomanize) EnableRule(pattern string) int

EnableRule enables rules matching the given pattern. Returns the number of rules enabled, or 0 if not supported.

func (*Gomanize) GetOptions

func (g *Gomanize) GetOptions() Options

GetOptions returns the current options.

func (*Gomanize) ListRules

func (g *Gomanize) ListRules(pattern string) []RuleStatus

ListRules returns all rules with their enabled/disabled status. If pattern is empty, returns all rules. Supports glob patterns (e.g., "schwa.*"). Returns nil if the romanizer doesn't support rule listing.

func (*Gomanize) SetOptions

func (g *Gomanize) SetOptions(opts Options)

SetOptions updates the options for this instance.

func (Gomanize) Test

func (g Gomanize) Test()

func (Gomanize) Translit

func (g Gomanize) Translit(sentence string) string

Translit transliterates text using the configured options. Words are segmented on ALL whitespace (spaces, tabs, newlines) AND punctuation — both preserved verbatim — so multi-line input romanizes line by line and attached punctuation (danda: "जीत।") no longer defeats word-final rules. Devanagari combining marks (matras, halant, nukta) are marks, not punctuation, so words are never split internally.

func (Gomanize) TranslitDebug

func (g Gomanize) TranslitDebug(word string) (string, *DebugInfo)

TranslitDebug transliterates a word and returns debug information.

type Options

type Options = core.Options

Options configures transliteration behavior. Use NewOptions() to get defaults, then modify as needed.

func NewOptions

func NewOptions() Options

NewOptions returns Options with default values.

type Romanizer

type Romanizer interface {
	Name() string
	Transliterate(word string) string
	TransliterateWithOptions(word string, opts Options) string
	TransliterateDebug(word string, opts Options) (string, *DebugInfo)
	Info()
}

type RuleStatus

type RuleStatus = core.RuleStatus

RuleStatus represents a rule and its current enabled/disabled state.