Contact
Carlos Lastres854 words

How to Fix Japanese Line Breaks on the Web

Browsers break Japanese text between almost any two characters, because Japanese has no spaces between words. To stop headings from splitting in the middle of a word, set lang="ja" and use word-break: auto-phrase, which Chrome has supported since version 119. For Safari and Firefox, add <wbr> by hand on short headings or run Google's BudouX library, the same phrase engine Chrome uses.

I design and build sites in Japanese, English, Spanish and Chinese from Tokyo, and line breaks are the detail that tells a Japanese reader within a second whether a site was made with care. A heading that ends with one lonely character on the second line looks broken, even when every word is correct.

Why Japanese breaks in the wrong place

English wraps at spaces, so a word stays whole unless it is longer than the line. Japanese is written without spaces, and the default rules allow a line break between almost any two characters. Body text is fine with that; readers are used to it. Headings, buttons and short ledes are not, because a break inside a word like 東京 or ダウンロード changes how the phrase reads and looks careless at large sizes.

There is also a set of rules called kinsoku. Certain characters should never start a line, such as small kana, closing brackets and the full stop 。, and some should never end one, such as opening brackets. The W3C has written all of this down in Requirements for Japanese Text Layout, and it is worth skimming once even if you never read it end to end. Japan's Digital Agency treats typography as a living part of its own design system too; I wrote about how often it revises it in Japan's government ships a better design system than most of its exporters.

auto-phrase: the one line fix in Chrome

Chrome added a value to word-break that breaks only between natural phrases. Google's write up on CSS internationalization features says it shipped in Chrome 119, needs the content language to be Japanese, and uses a C++ port of BudouX, a small machine learning model, to find phrase boundaries.

<html lang="ja">

h1, h2, h3, .lede, button {
  word-break: auto-phrase;
}

Two details catch people. The lang attribute has to resolve to Japanese for the element, so a multilingual site needs the right lang on every page or block. And I keep it to headings and short text. On long paragraphs, phrase breaking leaves a ragged right edge, and the default behavior reads better.

What to do in Safari and Firefox

According to MDN's browser compatibility data, Firefox does not support auto-phrase yet and Safari has it only in Technology Preview. In those browsers the property is ignored and you get the default breaks, so it is safe to ship, but it is not a fix for iPhone users.

For a handful of headings, the honest fix is manual. Put <wbr> at the phrase boundaries and add word-break: keep-all, which tells the browser not to break CJK text anywhere except those opportunities. Test it at phone width, because keep-all without enough break points will overflow.

For anything larger, BudouX does the same job in code. Its README describes it as standalone, around 15 KB including the model, with pretrained models for Japanese, Simplified Chinese, Traditional Chinese and Thai. I run it at build time over headings, so the HTML ships with the break hints already in it and no script runs in the browser.

Spacing and punctuation

Line breaks are half the job. Japanese fonts draw punctuation like 「 and 、 inside a full width box, which leaves visible gaps in headings. text-spacing-trim trims that space, and MDN's data shows it in Chrome since version 123, not yet in Safari or Firefox. The font feature palt does a similar job through the font itself and works wherever the font supports it:

h1 { font-feature-settings: "palt"; }

Use palt on headings and leave body text alone. Proportional spacing over long paragraphs makes Japanese harder to read.

text-autospace adds a small gap between Japanese and Latin letters or numbers, the space a designer would otherwise type by hand around "iPhone" in a sentence. It is newer and support differs by browser, so check the current table before relying on it.

And set line-break: strict if you want the stricter kinsoku rules, for example keeping small kana like ょ off the start of a line. It is supported in current Chrome, Firefox and Safari.

A short checklist

  • The right lang on every page and on any mixed language block.
  • word-break: auto-phrase on headings, ledes and buttons.
  • <wbr> or BudouX for the headings that matter in Safari.
  • palt on display text, default spacing on body text.
  • Line height a little looser for Japanese body text than for English, and tight on headings.
  • A real look at 390 pixels wide, in Safari, before shipping.

Line breaks rarely make a launch checklist. In Japan they decide whether a page reads as finished, the same way small details carry trust everywhere else in Japanese UX. Most of the fixes above take an afternoon.

← All posts