native-liblouis

Use the Liblouis braille translation engine in React Native + Expo (iOS, Android) and on the web (WASM). Out of the box, the package bundles:

• UEB Uncontracted (en-ueb-g1.ctb)
• UEB Contracted (en-ueb-g2.ctb)
• Their required include dependencies

You can add more tables and ship them with your app.

Table of Contents

• Live Demo
• Install
• API
  • lou_translateString
  • lou_translateBackString
  • lou_initialize (web only)
  • lou_isInitialized
• Managing Tables
  • Add/Remove with the CLI
  • Sync native modules
• Using your locally built package
  • Pack and install in your app
  • Monorepo/dev alt
• TODO
• License

Live Demo

Website: https://hen1227.github.io/native-liblouis/

Install

# Using npm
npm install native-liblouis

# Or using yarn
yarn add native-liblouis

Want to use a locally modified build (e.g., with extra/other tables)? See Using your locally built package.

API

LibLouis provides a lot of functionality. However, native-liblouis only exposes the following functions:

lou_translateString(input: string, table: string): string

Translates a string using the specified LibLouis table. Returns the translated string in Braille ASCII format.

import { lou_translateString } from 'native-liblouis';

const table = 'unicode.dis,en-ueb-g2.ctb'; // includes ASCII mapping
const result = lou_translateString(
  'Hello world',
  table
);

console.log(result); // ⠓⠑⠇⠇⠕ ⠺⠕⠗⠇⠙

lou_translateBackString(input: string, table: string): string

Translates a Braille ASCII string back to text using the specified LibLouis table. Returns the translated string in text format.

const table = 'unicode.dis,en-ueb-g2.ctb';
const braille = '⠓⠑⠇⠇⠕ ⠺⠕⠗⠇⠙';

const result = lou_translateBackString(
  braille,
  table
);

console.log(result); // Hello world

lou_initialize(): Promise<void> (Web only)

Initializes the LibLouis library and loads the bundled tables. Must be called before using any translation functions on web. On iOS and Android, initialization happens automatically.

if (Platform.OS === 'web') {
  await lou_initialize();
}

lou_isInitialized(): boolean

Returns whether the LibLouis library has been initialized.

if (!lou_isInitialized()) {
  console.warn('LibLouis not ready yet');
}

See the example app for a full usage example.

Managing Tables

You can ship extra Liblouis tables with your app. This repo includes a few npm-based tools and scripts.

Add/Remove with the CLI

# Add tables (will also pull required dependencies via `include` directives)
npm run tables:add en-ueb-math.ctb
npm run tables:add da-dk-g2.ctb vi-vn-g2.ctb

# Remove a table
npm run tables:remove en-ueb-math.ctb

# List bundled tables
npm run tables:list

# Clear them all
npm run tables:clear

The CLI automatically resolves dependencies and downloads tables from the LibLouis repository.

You can also drop .ctb/.utb/.dis/.cti files manually into bundled_tables/, but the CLI is safer and resolves dependencies.

Sync native modules

• Only tables changed (native + web by default):

  npm run tables:sync

  This updates the list of tables bundled in the native modules. Because the web build embeds tables in the WASM bundle, this step also rebuilds the WebAssembly module with the new tables.

• If you don’t need web updated, you can skip WASM work with:

  npm run tables:sync:noweb

• Rebuild native modules (iOS/Android C/C++ libs):

  npm run rebuild-native

After syncing or rebuilding, pack and reinstall the package in your app (see next section).

Using your locally built package

Pack and install in your app

When you’ve updated tables or rebuilt natives:

# In native-liblouis repo root
npm pack
# => produces something like native-liblouis-0.2.0.tgz

Then, in your app:

# From your app’s root
npm i ../path/to/native-liblouis/native-liblouis-0.2.0.tgz
# or with yarn/pnpm if you prefer

You can also point package.json to the tarball:

{
  "dependencies": {
    "native-liblouis": "file:../native-liblouis/native-liblouis-0.2.0.tgz"
  }
}

Monorepo/dev alt

For quick iteration you can use a file: folder dep:

{
  "dependencies": {
    "native-liblouis": "file:../native-liblouis"
  }
}

…but for reproducible builds and CI, prefer the tarball produced by npm pack.

TODO

• [ ] Allow runtime table loading from custom table path
• [ ] Add more tests
• [ ] Add more documentation

License

This project is licensed under the LGPL-2.1 or later license. See the LICENSE file for details. Liblouis itself is licensed under the LGPL-2.1 or later license.

Contributing

Any contributions are welcome! If you find a bug, have a feature request, or want to improve the documentation, please open an issue or submit a pull request. Here are some people who have contributed to native-liblouis so far:

And a special thanks to Liblouis for providing the braille translation engine that powers this package.