Braillify Korean Braille Translation Library

Braillify is a fully open-source Korean Braille translation library. It is designed to comply with the 2024 revised Korean Braille regulations and is licensed under the Apache License 2.0.

Key features include:

• Compliance: Adheres to the 2024 revised Korean Braille standards.
• Open Source: Fully open-source under Apache License 2.0.
• Performance: Built with Rust for native performance.
• Multi-language Support: Provides bindings for popular languages including Node.js, Python, C, Go, Java/Kotlin (JVM), and .NET.

braillify is a real-time Korean Braille translation library. Key features include:

• 2024 Revised Korean Braille Standards: Designed and implemented based on the latest 2024 regulations, providing context-aware and accurate translations.
• Fully Open Source: Unlike many existing Braille translators that rely on closed-source APIs, braillify is fully open-source, allowing for local execution and community improvement.
• Rust-based Cross-platform Support: Built with Rust, it supports Node.js, Rust, and Python environments. It also supports WebAssembly (Wasm), enabling local execution without network dependencies.

Korean rule 29 specifies that for consecutive Roman items, the Roman indicator is placed only before the first item and the terminator only after the last (e.g., Los Angeles).

The Re-entry Problem: A duplicate-event boundary can occur when the character emitter is already in Roman mode (e.g., after a mixed Korean/punctuation word) and encounters a later uppercase word. This can cause the system to incorrectly insert an explicit Roman-entry event.

The Fix: The EnterEnglish event is made idempotent. If the final emit state is already inside a Roman section, the event neither names an input nor changes the entry of a new section. This prevents duplicate events without changing the underlying multiword ASCII text processing.

When handling Roman text within a Korean sentence at a hyphen boundary, the engine uses the following routing logic based on Korean rules 29, 33, and 35-36:

Note on Compatibility: The analyzer applies U+2160-U+217F compatibility expansion before testing word grammar. For example, 천궁-Ⅱ is audited as the equivalent 천궁-II boundary.

When processing ampersands in Braille translation, determine if the ampersand is part of a single Roman character run or a standalone symbol.

Key considerations:

• Integrated Sequences: Patterns like A&B, S&P500, R&D, or AT&T5G may be treated as a single Roman character run.
• Right-side only: Structures like &c (where only the right side has Roman characters) require specific boundary handling.
• Contextual Priority: When an ampersand is attached to Korean characters (e.g., 과학&ICT), a standalone symbol (e.g., 종이접기 & 클레이아트), or inside parentheses (e.g., &TEAM), the priority of Braille rules must be determined based on whether it is treated as a symbol or part of a Roman run.
• Numeric Continuity: If a number follows an ampersand (e.g., S&P500), check if the Roman-to-Number continuity rules (Rule 35) apply.

A significant portion of mismatches in the NIKL 2025 v1.0 corpus are flagged as pending_rule_review with the sub-reason foreign_text_rule_review. These typically occur when the engine processes alphanumeric strings, acronyms (e.g., SPRi, SSEn, COO, CTO), or mixed-language contexts.

When debugging, check the first differing cell (zero-based) to pinpoint exactly where the Braille translation deviates from the expected standard for foreign/alphanumeric text.

The NIKL 2025 v1.0 corpus analysis is used to evaluate the accuracy of the Braillify engine against expected Braille outputs. The analysis categorizes results into three primary states:

• exact: The actual Braille output matches the expected output perfectly.
• localized_mismatch: The output differs from the expected output, often due to specific rule triggers (e.g., foreign_text_rule_review). These are often flagged as pending_rule_review.
• mismatch: General discrepancies that may be caused by suspected corpus issues or specific rule violations (e.g., rule34_roman_indicator_before_opening_parenthesis).

When debugging, the first differing cell (zero-based) index identifies exactly where the engine's output diverged from the expected sequence.

According to NIKL Q&A #325, the six lower wordsigns specified by Korean Rule 37 remain expanded when Roman words are discussed within a Korean context.

In contrast, a recognizable English title or phrase follows UEB 10.5 and uses a lower wordsign only when it stands alone and satisfies the lower-sign adjacency restriction. The encoder distinguishes these contexts based on input structure, capitalization, and enclosure boundaries, rather than analyzer references or competitor fields.

According to UEB 8.4.2, capitals-word mode terminates at a nonalphabetic symbol. For segments joined by an ampersand (e.g., AT&T or B&B), the Roman mode remains continuous, but capitalization restarts for each ASCII-letter segment.

Braillify's detector for this pattern:

• Accepts only complete uppercase ASCII segments joined directly by &.
• Requires the run to begin at its whitespace-delimited token.
• Excludes occurrences that are Korean-attached or punctuation-prefixed.