Skip to content

ytiurin/hyphen

Repository files navigation

Franklin M. Liang's hyphenation algorithm

npm version All Contributors

hyphen

Demo page

This is a text hyphenation library, based on Franklin M. Liang's hyphenation algorithm. In core of the algorithm lies a set of hyphenation patterns. They are extracted from hand-hyphenated dictionaries. Patterns for this library were taken from ctan.org and ported to Javascript.

import { hyphenate } from "hyphen/en";

(async () => {
  const text = "A certain king had a beautiful garden";

  const result = await hyphenate(text);
  // result is "A cer\u00ADtain king had a beau\u00ADti\u00ADful garden"
})();

Hyphenate HTML

Processor will automaticly skip HTML tags hyphenation.

import { hyphenate } from "hyphen/en";

(async () => {
  const text = "<blockquote>A certain king had a beautiful garden</blockquote>";

  const result = await hyphenate(text);
  // result is "<blockquote>A cer\u00ADtain king had a beau\u00ADti\u00ADful garden</blockquote>"
})();

Multilingual hyphenation

To hypehante text in any other supported language, just change the import source. For example for German language, import a hyphenation function from a "hyphen/de" source.

import { hyphenate } from "hyphen/de";

(async () => {
  const text = "Ein gewisser König hatte einen wunderschönen Garten";

  const result = await hyphenate(text);
  // result is "Ein ge\u00ADwis\u00ADser Kö\u00ADnig hat\u00ADte einen wun\u00ADder\u00ADschö\u00ADnen Gar\u00ADten"
})();

It is possible to use many langauges on the same page.

import { hyphenate as hyphenateEn } from "hyphen/en";
import { hyphenate as hyphenateDe } from "hyphen/de";

(async () => {
  const english = "A certain king had a beautiful garden";

  const englishResult = await hyphenateEn(english);
  // result is "A cer\u00ADtain king had a beau\u00ADti\u00ADful garden"

  const deutch = "Ein gewisser König hatte einen wunderschönen Garten";

  const deutchResult = await hyphenateDe(deutch);
  // result is "Ein ge\u00ADwis\u00ADser Kö\u00ADnig hat\u00ADte einen wun\u00ADder\u00ADschö\u00ADnen Gar\u00ADten"
})();

Sync version

The hyphenate function returns a Promise, however a sync version of it returns a string.

import { hyphenateSync as hyphenate } from "hyphen/en";

const text = "A certain king had a beautiful garden";

const result = hyphenate(text);
// result is "A cer\u00ADtain king had a beau\u00ADti\u00ADful garden"

Install

npm install hyphen

Install types definitions for Typescript usage.

npm install --save-dev @types/hyphen

Types definitions are created and maintained by Krisztián Balla.

Options

  • exceptions

    An Array of values with exceptions of hyphenation in words. Hard hyphen symbol - should be used to mark the position of further configured hyphenation symbol. Default value is [].

  • hyphenChar

    A String sets a value of the soft hyphen character. Default value is \u00AD.

  • minWordLength

    A Number sets the minimum length of the word, intended for hyphenation. Default value is 5.

Example of using options

import { hyphenate } from "hyphen/en";

(async () => {
  const text = "A certain king had a beautiful garden";

  const result = await hyphenate(text, {
    hyphenChar: "-"
  });
  // result is "A cer-tain king had a beau-ti-ful garden"
})();

List of available languages

Check the list
  • Afrikaans language
import { hyphenate } from "hyphen/af";
  • Assamese language
import { hyphenate } from "hyphen/as";
  • Belarusian language
import { hyphenate } from "hyphen/be";
  • Bulgarian language
import { hyphenate } from "hyphen/bg";
  • Bengali language
import { hyphenate } from "hyphen/bn";
  • Catalan language
import { hyphenate } from "hyphen/ca";
  • Coptic language
import { hyphenate } from "hyphen/cop";
  • Czech language
import { hyphenate } from "hyphen/cs";
  • Welsh language
import { hyphenate } from "hyphen/cy";
  • Church Slavonic language
import { hyphenate } from "hyphen/cu";
  • Danish language
import { hyphenate } from "hyphen/da";
  • German, traditional spelling
import { hyphenate } from "hyphen/de-1901";
  • German, reformed spelling
import { hyphenate } from "hyphen/de-1996";
  • German, traditional Swiss spelling
import { hyphenate } from "hyphen/de-CH-1901";
  • Modern Greek, monotonic spelling
import { hyphenate } from "hyphen/el-monoton";
  • Modern Greek, polytonic spelling
import { hyphenate } from "hyphen/el-polyton";
  • English, British spelling language
import { hyphenate } from "hyphen/en-gb";
  • English, American spelling language
import { hyphenate } from "hyphen/en-us";
  • Spanish language
import { hyphenate } from "hyphen/es";
  • Estonian language
import { hyphenate } from "hyphen/et";
  • Basque language
import { hyphenate } from "hyphen/eu";
  • Finnish language
import { hyphenate } from "hyphen/fi";
  • French language
import { hyphenate } from "hyphen/fr";
  • Friulan language
import { hyphenate } from "hyphen/fur";
  • Irish language
import { hyphenate } from "hyphen/ga";
  • Galician language
import { hyphenate } from "hyphen/gl";
  • Ancient Greek language
import { hyphenate } from "hyphen/grc";
  • Gujarati language
import { hyphenate } from "hyphen/gu";
  • Hindi language
import { hyphenate } from "hyphen/hi";
  • Croatian language
import { hyphenate } from "hyphen/hr";
  • Upper Sorbian language
import { hyphenate } from "hyphen/hsb";
  • Hungarian language
import { hyphenate } from "hyphen/hu";
  • Armenian language
import { hyphenate } from "hyphen/hy";
  • Interlingua language
import { hyphenate } from "hyphen/ia";
  • Bahasa Indonesia, Indonesian language
import { hyphenate } from "hyphen/id";
  • Icelandic language
import { hyphenate } from "hyphen/is";
  • Italian language
import { hyphenate } from "hyphen/it";
  • Georgian language
import { hyphenate } from "hyphen/ka";
  • Kurmanji, Northern Kurdish language
import { hyphenate } from "hyphen/kmr";
  • Kannada language
import { hyphenate } from "hyphen/kn";
  • Classical Latin language
import { hyphenate } from "hyphen/la-x-classic";
  • Liturgical Latin language
import { hyphenate } from "hyphen/la-x-liturgic";
  • Latin language
import { hyphenate } from "hyphen/la";
  • Lithuanian language
import { hyphenate } from "hyphen/lt";
  • Latvian language
import { hyphenate } from "hyphen/lv";
  • Malayalam language
import { hyphenate } from "hyphen/ml";
  • Mongolian, Cyrillic script, alternative patterns
import { hyphenate } from "hyphen/mn-cyrl-x-lmc";
  • Mongolian, Cyrillic script
import { hyphenate } from "hyphen/mn-cyrl";
  • Marathi language
import { hyphenate } from "hyphen/mr";
  • Multiple languages using the Ethiopic scripts
import { hyphenate } from "hyphen/mul-ethi";
  • Norwegian Bokmål, bokmål, norsk bokmål language
import { hyphenate } from "hyphen/nb";
  • Dutch language
import { hyphenate } from "hyphen/nl";
  • Norwegian Nynorsk, nynorsk language
import { hyphenate } from "hyphen/nn";
  • Norwegian, norsk language
import { hyphenate } from "hyphen/no";
  • Occitan language
import { hyphenate } from "hyphen/oc";
  • Odia, Oriya language
import { hyphenate } from "hyphen/or";
  • Panjabi, Punjabi language
import { hyphenate } from "hyphen/pa";
  • Pāli language
import { hyphenate } from "hyphen/pi";
  • Polish language
import { hyphenate } from "hyphen/pl";
  • Piedmontese language
import { hyphenate } from "hyphen/pms";
  • Portuguese language
import { hyphenate } from "hyphen/pt";
  • Romansh language
import { hyphenate } from "hyphen/rm";
  • Romanian language
import { hyphenate } from "hyphen/ro";
  • Russian language
import { hyphenate } from "hyphen/ru";
  • Sanskrit language
import { hyphenate } from "hyphen/sa";
  • Serbocroatian, Cyrillic script
import { hyphenate } from "hyphen/sh-cyrl";
  • Serbocroatian, Latin script
import { hyphenate } from "hyphen/sh-latn";
  • Slovak language
import { hyphenate } from "hyphen/sk";
  • Slovenian language
import { hyphenate } from "hyphen/sl";
  • Serbian, Cyrillic script
import { hyphenate } from "hyphen/sr-cyrl";
  • Swedish language
import { hyphenate } from "hyphen/sv";
  • Tamil language
import { hyphenate } from "hyphen/ta";
  • Telugu language
import { hyphenate } from "hyphen/te";
  • Thai language
import { hyphenate } from "hyphen/th";
  • Turkmen language
import { hyphenate } from "hyphen/tk";
  • Turkish language
import { hyphenate } from "hyphen/tr";
  • Ukrainian language
import { hyphenate } from "hyphen/uk";
  • Mandarin Chinese, pinyin transliteration
import { hyphenate } from "hyphen/zh-latn-pinyin";

Aliases for specific languages

  • Alias for hyphen/de-1996
import { hyphenate } from "hyphen/de";
  • Alias for hyphen/el-monoton
import { hyphenate } from "hyphen/el";
  • Alias for hyphen/en-us
import { hyphenate } from "hyphen/en";
  • Alias for hyphen/mul-ethi
import { hyphenate } from "hyphen/ethi";
  • Alias for hyphen/mn-cyrl
import { hyphenate } from "hyphen/mn";
  • Alias for hyphen/sh-cyrl
import { hyphenate } from "hyphen/sh";
  • Alias for hyphen/sr-cyrl
import { hyphenate } from "hyphen/sr";
  • Alias for hyphen/zh-latn-pinyin
import { hyphenate } from "hyphen/zh";

Factory function

Factory function can be used to create hyphenate function with changed default options.

Create hyphenation function with predefined exception list

import createHyphenator from "hyphen";
import patterns from "hyphen/patterns/en-us";

const hyphenate = createHyphenator(patterns, {
  // result in Promise
  async: true,
  // exceptions of hyphenation
  exceptions: ["present", "ta-ble"]
});

Predefined functions

The following are predefined hyphenate functions.

import createHyphenator from "hyphen";
import patterns from "hyphen/patterns/en-us";

const hyphenate = createHyphenator(patterns, {
  async: true
});

const hyphenateSync = createHyphenator(patterns);

Predefined hyphenate functions are set in every language pack.

jsDelivr CDN for older websites

It is possible to use hyphen on older websites with jsDelivr network. Check the package page on their website.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/patterns/en-us.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/hyphen.min.js"></script>

After the script is added on your page, use еру createHyphenator to create a hyphenate function.

var hyphenate = createHyphenator(hyphenationPatternsEnUs, {
  async: true
});

Alternatives

Check other great hyphenation libraries:

  • Hyphenopoly does client-side hyphenation of HTML-Documents.
  • Hypher A fast and small hyphenation engine.

Text hyphenation in CSS

The CSS hyphens property is intended to add hyphenation support to modern browsers without Javascript:

p {
  hyphens: auto;
}

It is part of the CSS Text Level 3 specification. The browser compatibility list can be found on the related MDN page.

DEPRECATED

  • Option debug will be deprecated in further versions;

Migration

from 1.9.1 to 1.10.0

Option html default value changed from false to true

In cases when text parser should not skip HTML tags, apply the following code changes.

Default exported hyphenate function

// Code before 1.10.0
hyphenate(text);
// Code after 1.10.0
hyphenate(text, { html: false });

Create hyphenate function with pre 1.10.0 behavior using a factory function:

// Code after 1.10.0
const hyphenate = createHyphenator(patterns, {
  async: true,
  html: false
});

hyphenate(text);

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Eugene Tiurin
Eugene Tiurin

🤔 💻 🚧
Krisztián Balla
Krisztián Balla

🐛 🧑‍🏫 📣
Robin Millette
Robin Millette

💻 🐛
Asko Soukka
Asko Soukka

💻 🐛
Nicolas Sierra
Nicolas Sierra

💻 🐛
Jaume Ortolà
Jaume Ortolà

💻 🐛
Simon Osterlehner
Simon Osterlehner

💻
Jason Wohlgemuth
Jason Wohlgemuth

📖
Kamil Mielnik
Kamil Mielnik

💻 🐛
Oskar Köök
Oskar Köök

💻 🐛
Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!