Hyphenation

Liang's algorithm

Hyphenator implements the algorithm Frank Liang designed for TeX, written from scratch. A pattern is a string of letters with digits between them — .ach4, a1b, hy3ph —, the dot marking the start or the end of a word. Every pattern found in the word, framed by dots, raises the digits between its letters; a break is allowed where the highest digit is odd, never closer to either end than the language's minimum lengths, and never before a combining mark. A word listed among the exceptions — ta-ble, project — breaks where the exception says.

$hyphenator = Hyphenator::for('en_US');
$hyphenator->breaks('hyphenation');          // [2, 6]
$hyphenator->hyphenate('hyphenation', '-');  // hy-phen-ation
$hyphenator->hyphenate('hyphenation');       // with soft hyphens (U+00AD), the default

A word whose lower case does not have as many characters as the word itself — İstanbul — is left whole. The minimum lengths of the language can be replaced: new Hyphenator($patterns, left: 3, right: 3); neither is below one.

Languages

Dictionary finds the patterns of a locale through its candidates and a table of aliases, or takes a pattern tag directly (de-1901, la-x-classic, fi-x-school). Most patterns are those of hyph-utf8 (version 2026-02-21), the hyphenation patterns of TeX in UTF-8, imported for every language whose licence permits them in an MIT package; each file is a verbatim copy, and data/LICENSES reproduces the header of the source file with its copyright and licence. Where a file is offered under several licences, the permissive one is used. Seven languages whose TeX patterns carry a reciprocal licence or none have patterns written for this library, under its MIT licence: see Patterns written for this library.

de gives the reformed spelling, de_CH and de_LI the traditional Swiss spelling, de-1901 the traditional spelling; el gives the monotonic spelling, el-polyton the polytonic one; Norwegian Bokmål and Nynorsk share the patterns of hyph-no, under the Nynorsk tag; Serbian is read through the Serbo-Croatian patterns, in Cyrillic for sr and in Latin script for sr_Latn.

Patterns written for this library

The TeX patterns of Czech (GPL 2 or later only), Hungarian (MPL 1.1, GPL 2 or LGPL 2.1 only), Armenian (LGPL only), Indonesian (GPL only), Latvian (LGPL 2.1 or GPL 2 only), Macedonian (GPL only) and Romanian (no licence stated) cannot be shipped in an MIT package. These seven languages have patterns written from scratch instead, from the published orthographic rules of each language — no pattern, exception list or word list under another licence was read to write them. The rules are written as data in tests/Generator/SyllableRules.php, tests/Generator/PatternGenerator.php turns them into Liang patterns, php bin/generate-patterns.php writes the <tag>.pat.txt files, and the tests check that the shipped files are those the rules give.

They are rules, not a dictionary — less complete than the TeX patterns. A rule of syllabification sees letters, not words: it cannot tell a compound or a prefix from a syllable, nor a diphthong from two vowels written alike. Where the rules of a language depend on that, the patterns allow no break rather than a wrong one, so they miss breaks the TeX patterns find, and a word outside the rules may still break where a dictionary would not. Each language is tested on a list of common words that must break exactly where its rules allow.

Experimental languages

The rules of Armenian and Macedonian are the least certain of the seven: they still wait for a reading by a speaker of each language. Their patterns ship, but they are experimental and off by default: a Dictionary serves them only when it is built with their tags, listed in Dictionary::EXPERIMENTAL. Without them, hy and mk have no patterns — supports() is false, the presets leave hyphen out and patterns() throws UnsupportedLanguage.

$dictionary = new Dictionary(experimental: ['hy']);    // Armenian served, Macedonian still off
$dictionary = new Dictionary(experimental: Dictionary::EXPERIMENTAL);
Typographer::for('hy_AM', dictionary: $dictionary);

A tag outside Dictionary::EXPERIMENTAL given there changes nothing: the other languages are always served. In Symfony, phil/typography-bundle sets the list with experimental_hyphenation.

An application that accepts the licence of the TeX patterns of one of these languages and wants their completeness loads them itself, as Patterns of your own shows.

Thai: word breaks

Thai is written without spaces between words and breaks a line between words without a visible hyphen, which a soft hyphen cannot express. Its preset runs the word_break fixer instead of hyphen: WordBreak puts a zero-width space (U+200B) at each line-break opportunity that ICU finds in a run of Thai characters, through IntlBreakIterator and its Thai dictionary, so that a browser without a dictionary of its own still breaks the line between two words. The fixer runs only where hyphenation is asked for (Typographer::for('th', hyphenation: false) leaves it out). ext-intl is already a requirement of the library, for Normalizer, so the fixer needs nothing more. A fixer never adds markup, so the break is a character, not a <wbr> element; the two behave alike in a browser.

Typographer::for('th_TH')->fixText('สวัสดีครับ'); // "สวัสดี\u{200B}ครับ"

The breaks are those of the ICU the PHP build links to, and may differ slightly from one ICU version to the next.

Left out

For these tags, and for Thai, Dictionary::supports() is false, the presets leave Hyphen out, and Hyphenator::for() throws UnsupportedLanguage.

Patterns of your own

new Dictionary($directory) reads <tag>.pat.txt and <tag>.hyp.txt from another directory, for the same tags; a missing exceptions file means none, and supports() is true only when the patterns file is there. Patterns can also be given directly:

$patterns = Patterns::parse(file_get_contents('hyph-cs.pat.txt'), file_get_contents('hyph-cs.hyp.txt'), 2, 3);
$hyphenator = new Hyphenator($patterns);

That is how an application uses patterns under a licence this library does not ship, under its own responsibility.

Performance

A dictionary reads the patterns of a language once and keeps them: the German patterns, the largest, take about forty milliseconds to read. Typographers shares one dictionary between its typographers; a long-running process should keep its typographers rather than build them for each request.