@romanize-string/thai-engine

Thai-romanizer is a Node-only Thai romanization plugin for romanize-string. It runs a platform-specific binary (~50 MB) to romanize Thai script using the Python library PyThaiNLP.

See the Changelog for details on recent updates.

Features

• Works with romanize-string's plugin system.
• Automatically downloads the appropriate platform-specific binary (~50 MB) at install.
• Fails fast with a clear error if the binary is missing or not executable.

Installation

npm install @romanize-string/thai-engine

Requires Node.js 18+

Note: This plugin extends romanize-string and must be used together with it. It will not function without romanize-string installed in your project. This package does not provide end‑user APIs by itself; it only supplies a plugin function to be registered with romanize-string.

Usage

ESM

import romanizeString, {romanizeThai} from "romanize-string"
import thaiEngine from "@romanize-string/thai-engine"

romanizeString.register(thaiEngine)

console.log(await romanizeString("สวัสดี ครับ", "th")) //sawatdi khrap

console.log(romanizeThai("สวัสดี ครับ")) //sawatdi khrap

CommonJS

const {default: romanizeString, romanizeThai} = require("romanize-string")
const thaiEngine = require("@romanize-string/thai-engine")

romanizeString.register(thaiEngine)

console.log(await romanizeString("สวัสดี ครับ", "th")) //sawatdi khrap

console.log(romanizeThai("สวัสดี ครับ")) //sawatdi khrap

Registration scope

Call romanizeString.register(thaiEngine) once per process (e.g., at app start) to enable Thai support. After registration, any call to romanizeString("…", "th") in the same process will work without re-registering.

Security note

Downloaded helper binaries are verified against a known checksum during installation. The binaries are built from source that lives in this same repository; no third‑party download service is used.

Version compatibility

Requires a version of romanize-string that exposes the plugin registration hook (via Symbol.for("romanize-string.registerPlugin")). If you see the error "The romanize-string plugin hook was not found; plugin not registered.", upgrade romanize-string and ensure there's only a single installed copy.

Supported platforms

| Platform | Binary name | | -------------- | ----------------------- | | darwin-arm64 | thai-mac-arm64 | | darwin-x64 | thai-mac-x64 | | linux-arm64 | thai-linux-arm64 | | linux-x64 | thai-linux-x64 | | win32-x64 | thai-win-x64.exe | | win32-arm64 | thai-win-x64.exe (runs under emulation) |

Error messages & troubleshooting

• "The romanize-string plugin hook was not found; plugin not registered."
  This means the plugin could not connect to the main romanize-string library. In most cases, this happens if you are using an older version of romanize-string, have multiple copies of it installed, or are running in an unusual environment where global settings are not shared.

  How to fix: Make sure you are on a recent version of romanize-string, that your project only has one copy installed, and that you are running in a normal Node.js environment.

• "Cannot register plugin. The thaiEngine binary is missing or was not successfully downloaded."
  The platform-specific binary was not found or could not be executed. Try reinstalling the package. If this persists, check that your system is supported and that you have permission to execute the binary.

• "Romanization returns the original text"
  If romanization silently returns the input text, the native helper likely failed at runtime or was not registered. Try these quick checks:

  • Ensure you've called romanizeString.register(thaiEngine) once before first use.
  • Verify your Node version is supported (Node 18+ recommended).
  • Confirm file permissions allow execution of the bundled helper (on Unix-like systems, it should be executable by the current user).
  • Reinstall the package to re-fetch the correct binary for your platform: rm -rf node_modules && pnpm install (or npm ci).
  • Check for duplicate installs of romanize-string that can break the global registration: npm ls romanize-string or pnpm why romanize-string.

Licenses & attribution

This package redistributes third-party components (e.g., PyThaiNLP, NumPy, ONNX Runtime). Full license texts for these and for the PyInstaller bootloader are included in third_party/.