honocoroko

A TypeScript library for transliterating text between Latin and Javanese script (Aksara Jawa/Hanacaraka).

[!IMPORTANT] This library changes writing systems (Latin ↔ Javanese script), not languages. It's transliteration, not translation.

Installation

npm install @naandalist/honocoroko

Usage

Import Methods

The package supports both ESM (ES Modules) and CommonJS:

🔥 ESM (Modern) - Recommended

Use this in modern Node.js projects, TypeScript, Vite, or any bundler that supports ES modules:

import { toHonocoroko, fromHonocoroko, transliterate } from '@naandalist/honocoroko';

🔧 CommonJS (Legacy)

Use this in older Node.js projects or when require() is needed:

const { toHonocoroko, fromHonocoroko, transliterate } = require('@naandalist/honocoroko');

Basic Examples

// Convert Latin text to Javanese script
const javanese = toHonocoroko('hanacaraka');
console.log(javanese); // ꦲꦤꦕꦫꦏ

// Convert Javanese script back to Latin
const latin = fromHonocoroko('ꦲꦤꦕꦫꦏ');
console.log(latin); // hanacaraka

// Using the generic transliterate function
const result1 = transliterate('hanacaraka', 'toHonocoroko');
const result2 = transliterate('ꦲꦤꦕꦫꦏ', 'fromHonocoroko');

⚡ TypeScript Projects

import { 
  toHonocoroko, 
  fromHonocoroko, 
  TransliterationDirection, 
  TransliterationOptions 
} from '@naandalist/honocoroko';

const javanese: string = toHonocoroko('hanacaraka');
const latin: string = fromHonocoroko('ꦲꦤꦕꦫꦏ');

// With options - opt-in to convert special characters
const options: TransliterationOptions = { convertSpecialChars: true };
const result: string = toHonocoroko('sapa iki?', options);

🌐 Browser/Bundlers (Webpack, Vite, etc.)

import { toHonocoroko } from '@naandalist/honocoroko';

// Works in React, Vue, Svelte, etc.
const transliterated = toHonocoroko('basa jawa');

Features

• ✅ Universal Module Support - Works with both ESM (import) and CommonJS (require)
• ✅ Full support for basic Javanese consonants (Aksara Nglegena)
• ✅ Vowels and vowel marks (Sandhangan)
• ✅ Special consonants (Aksara Murda)
• ✅ Javanese numerals (0-9)
• ✅ Javanese punctuation
• ✅ Phonetic approximations for Latin letters not in Javanese (f, v, z, q, x)
• ✅ TypeScript support with full type definitions
• ✅ Zero dependencies - lightweight and secure

Supported Characters

Basic Consonants

• ha (ꦲ), na (ꦤ), ca (ꦕ), ra (ꦫ), ka (ꦏ)
• da (ꦢ), ta (ꦠ), sa (ꦱ), wa (ꦮ), la (ꦭ)
• pa (ꦥ), dha (ꦝ), ja (ꦗ), ya (ꦪ), nya (ꦚ)
• ma (ꦩ), ga (ꦒ), ba (ꦧ), tha (ꦛ), nga (ꦔ)

Numbers

• 0-9 → ꧐-꧙

Punctuation

• Comma (,) → ꧈
• Period (.) → ꧉
• Colon (:) → ꧇

Phonetic Approximations

• f → ꦥ꦳ (pa + cecak telu)
• v → ꦮ꦳ (wa + cecak telu)
• z → ꦗ꦳ (ja + cecak telu)
• q → ꦏ (ka)
• x → ꦏ꧀ꦱ (ks)

Font Support

This package includes the HanacarakaFont.ttf in the /fonts directory for proper display of Javanese script.

Installing the Font

Windows

1. Navigate to node_modules/@naandalist/honocoroko/fonts/
2. Right-click on .ttf
3. Select "Install" or "Install for all users"

macOS

1. Navigate to node_modules/@naandalist/honocoroko/fonts/
2. Double-click on .ttf
3. Click "Install Font" in the preview window

API

toHonocoroko(text: string, options?: TransliterationOptions): string

Converts Latin text to Javanese script.

const javanese = toHonocoroko('hanacaraka');
// Returns: ꦲꦤꦕꦫꦏ

fromHonocoroko(text: string, options?: TransliterationOptions): string

Converts Javanese script back to Latin text.

const latin = fromHonocoroko('ꦲꦤꦕꦫꦏ');
// Returns: hanacaraka

transliterate(text: string, direction: 'toHonocoroko' | 'fromHonocoroko', options?: TransliterationOptions): string

Generic function that can transliterate in either direction.

const result1 = transliterate('hanacaraka', 'toHonocoroko');
const result2 = transliterate('ꦲꦤꦕꦫꦏ', 'fromHonocoroko');

Options

All transliteration functions accept an optional options parameter to customize behavior:

convertSpecialChars: boolean

By default, special characters like ?, !, @, ., etc. are preserved unchanged during transliteration. Set convertSpecialChars: true to attempt converting these characters to Hanacaraka approximations.

import { toHonocoroko, fromHonocoroko, transliterate } from '@naandalist/honocoroko';

// Default behavior - preserves special characters
const result1 = toHonocoroko('apa iki?');
// Returns: ꦄꦥ ꦆꦏꦶ? (question mark preserved)

const result2 = toHonocoroko('[email protected]');
// Returns: ꦌꦩꦆꦭ@ꦢꦺꦴꦩꦆꦤ.ꦕꦺꦴꦩ (@ and . preserved)

// Opt-in to convert special characters
const options = { convertSpecialChars: true };
const result3 = toHonocoroko('test?', options);
// Attempts to convert ? to Hanacaraka (may produce warnings if no mapping exists)

// Works with all functions
const result4 = transliterate('hello!', 'toHonocoroko', { convertSpecialChars: false });
// Returns: ꦲꦼꦭ꧀ꦭꦺꦴ! (exclamation mark preserved - this is default)

Function Signatures

toHonocoroko(text: string, options?: TransliterationOptions): string
fromHonocoroko(text: string, options?: TransliterationOptions): string
transliterate(text: string, direction: TransliterationDirection, options?: TransliterationOptions): string

interface TransliterationOptions {
  convertSpecialChars?: boolean; // Default: false (preserves special chars)
}

Default Preserved Characters

The following characters are preserved by default (when convertSpecialChars is false or not specified):

? ! @ # $ % ^ & * - _ = + [ ] { } | \ ; ' < > / ` ~

Note: Characters like , . : " ( ) have proper Javanese equivalents and will always be converted:

• , → ꧈
• . → ꧉
• : → ꧇
• " → ꧊꧋
• ( → ꧌
• ) → ꧍

License

MIT © Listiananda Apriliawan

NOTE: Free to use, modify, and distribute. Just keep the copyright notice.

Support

If you find this library helpful, you can buy me a coffee ☕

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

This library is inspired by the transliterasijawa project.