polyglossia — texthai.org

Polyglossia is the modern multilingual framework for XeLaTeX and LuaLaTeX. For Thai documents it does three things: activates Thai-aware line breaking, loads the correct hyphenation patterns, and lets you switch languages mid-document without manual font juggling. Use it instead of Babel for any XeLaTeX Thai work.

Minimal setup

Thai as the only language

\documentclass{article}
\usepackage{fontspec}
\usepackage{polyglossia}
\setmainlanguage{thai}
\setmainfont{TH Sarabun New}

\begin{document}
สวัสดี ภาษาไทย
\end{document}

Compile with xelatex filename.tex. That is the complete working document.

Thai as main language, English secondary

\documentclass{article}
\usepackage{fontspec}
\usepackage{polyglossia}

\setmainlanguage{thai}
\setotherlanguage{english}

\setmainfont{TH Sarabun New}[
  Script=Thai,
  BoldFont={TH Sarabun New Bold},
  ItalicFont={TH Sarabun New Italic}
]
\newfontfamily\englishfont{TeX Gyre Pagella}[
  Ligatures=TeX
]

\begin{document}

ข้อความภาษาไทยปกติ

\textenglish{This paragraph is in English, set in Pagella.}

ภาษาไทยอีกครั้ง ข้อความนี้ใช้แบบอักษรสารบรรณ

\end{document}

The \englishfont family switches automatically inside \textenglish{} blocks and english environments. You do not need to call it manually.

English as main language, Thai secondary

For documents that are primarily English with some Thai passages:

\setmainlanguage{english}
\setotherlanguage{thai}

\setmainfont{TeX Gyre Pagella}[Ligatures=TeX]
\newfontfamily\thaifont{TH Sarabun New}[Script=Thai]

\begin{document}

This is an English document.

\begin{thai}
ส่วนนี้เป็นภาษาไทย ใช้แบบอักษรและการตัดบรรทัดแบบไทย
\end{thai}

Back to English text.

\end{document}

The Script=Thai option

The Script=Thai option in fontspec activates the font's OpenType Thai layout features — correct vowel and tone mark positioning, proper glyph shaping. Without it, Thai text may render with marks in wrong positions or missing entirely, depending on the font.

% correct
\setmainfont{TH Sarabun New}[Script=Thai]

% also add Language=Thai for language-specific glyph variants
\setmainfont{TH Sarabun New}[Script=Thai, Language=Thai]

Script=Thai and Language=Thai are fontspec options, not polyglossia options. They go inside the \setmainfont[] brackets. A common mistake is to omit them when polyglossia is loaded, assuming polyglossia sets them automatically. It does not.

Line breaking

Thai has no spaces between words. XeLaTeX needs help knowing where to break lines. Polyglossia enables Thai line breaking automatically when \setmainlanguage{thai} is set — but only if the system has libthai or ICU available for word boundary detection.

For finer control, or if automatic breaking is not working, add these two primitives explicitly:

\XeTeXlinebreaklocale "th"
\XeTeXlinebreakskip = 0pt plus 1pt

Place these after \begin{document}, not in the preamble. They are XeTeX engine primitives, not LaTeX commands. The plus 1pt on linebreakskip gives the line breaker a small amount of flexibility; setting it to 0pt exactly can produce overfull boxes on short lines.

Full treatment of justification and line breaking is in linebreak/.

Common traps

symptom	cause and fix
\setmainlanguage called before \usepackage{polyglossia}	Always load polyglossia first, then call language commands. Order matters.
Undefined control sequence \textenglish	`\setotherlanguage{english}` was not called. Polyglossia only creates `\textX{}` commands for languages explicitly declared.
English text renders in Thai font	`\newfontfamily\englishfont{...}` was declared but polyglossia needs the family name to match exactly. Check that the family name is `\englishfont`, not a custom name.
Thai tone marks appear in wrong position	Missing `Script=Thai` in `\setmainfont[]`. Add it and recompile.
Overfull \hbox warnings throughout Thai text	Line breaking locale not active. Add `\XeTeXlinebreaklocale "th"` after `\begin{document}`.
Font not found error for TH Sarabun New	Font is not installed system-wide, or the name does not match. Run `fc-list \| grep -i sarabun` and use the exact registered name. See fonts/.
polyglossia conflicts with babel	Do not load both. For XeLaTeX Thai work, use polyglossia only. Remove any `\usepackage{babel}`.
\setotherlanguage{thai} has no effect on line breaking	Line breaking only activates fully when Thai is the main language or when XeTeX primitives are set explicitly. In English-main documents, add `\XeTeXlinebreaklocale "th"` inside Thai environments.

Polyglossia vs Babel for Thai

Babel's Thai support under pdfLaTeX is limited: it cannot load system fonts, has no OpenType shaping, and Thai line breaking depends on having the right hyphenation patterns compiled in. For any serious Thai typesetting, XeLaTeX + polyglossia is the right choice. Babel is documented in babel/ for cases where pdfLaTeX is a hard requirement.

Complete working example

Copy, compile with xelatex, and verify output before building your own document on top of it.

\documentclass[12pt, a4paper]{article}
\usepackage{fontspec}
\usepackage{polyglossia}

\setmainlanguage{thai}
\setotherlanguage{english}

\setmainfont{TH Sarabun New}[
  Script=Thai,
  Language=Thai,
  BoldFont={TH Sarabun New Bold},
  ItalicFont={TH Sarabun New Italic},
  BoldItalicFont={TH Sarabun New Bold Italic}
]
\newfontfamily\englishfont{TeX Gyre Pagella}[
  Ligatures=TeX,
  Numbers=OldStyle
]

\begin{document}

\XeTeXlinebreaklocale "th"
\XeTeXlinebreakskip = 0pt plus 1pt

\section{บทนำ}

ภาษาไทยเป็นภาษาที่ใช้อักษรไทย ซึ่งไม่มีการเว้นวรรคระหว่างคำ
การตัดบรรทัดต้องอาศัยการวิเคราะห์ทางภาษาศาสตร์

\textenglish{
  This section is in English.
  XeLaTeX switches fonts automatically
  via the polyglossia language mechanism.
}

กลับมาภาษาไทย ระบบสลับแบบอักษรโดยอัตโนมัติ

\end{document}

polyglossia/