Understanding Polyglossia for Modern LaTeX

In the early days of LaTeX, the babel package was the gold standard for multilingual support. However, with the advent of modern TeX engines like XeLaTeX and LuaLaTeX, a more powerful and flexible alternative emerged: Polyglossia.

Polyglossia is specifically designed to work with modern engines that support Unicode (UTF-8) natively. This makes it significantly easier to handle documents containing multiple languages, different scripts (like Arabic, Cyrillic, or Greek), and complex typographic requirements. Unlike older methods, Polyglossia leverages the fontspec package to allow you to use any font installed on your system.

Note: Polyglossia will not work with the traditional pdflatex engine. To use the features in this guide, you must compile your document using XeLaTeX or LuaLaTeX.

Setting Up Your Multilingual Document

To start using Polyglossia, you must first load the package and define which languages your document will use. You define one "main" language and any number of "other" languages.

Basic Configuration

In your preamble, you use \setmainlanguage for the primary language of your document and \setotherlanguage for secondary ones.

\documentclass{article}

% Required for loading system fonts
\usepackage{fontspec}

% Load polyglossia
\usepackage{polyglossia}

% Define languages
\setmainlanguage{english}
\setotherlanguage{french}
\setotherlanguage{greek}

% Set fonts (essential for non-Latin scripts)
\setmainfont{Times New Roman}
\newfontfamily\greekfont{Linux Libertine O} % Specific font for Greek

\begin{document}
This is a document in English. 
\end{document}

By defining languages this way, Polyglossia automatically handles:

Hyphenation rules for each language.
Localized strings (like "Chapter" vs "Chapitre").
Date formats.
Direction of text (Left-to-Right or Right-to-Left).

Switching Between Languages

Once your languages are defined in the preamble, you need to tell LaTeX when to switch between them in the body of your document. Polyglossia provides two main ways to do this: environments and commands.

1. The Language Environment

Use an environment when you have a large block of text (like a full paragraph) in a different language.

\begin{french}
Ceci est un paragraphe écrit en français. Polyglossia s'occupe de la ponctuation et de la césure.
\end{french}

2. The Inline Command

For short phrases or single words, use the \text<language>{...} command.

The motto of France is \textfrench{Liberté, Égalité, Fraternité}.
In Greek, the word for "book" is \textgreek{βιβλίο}.

3. Manual Switching

If you want to switch the language for the remainder of the document (or until the next switch), use \selectlanguage{language_name}.

Advanced Customization and Options

One of Polyglossia’s greatest strengths is its ability to fine-tune how specific languages behave. Many languages have "options" that you can pass during definition or switching.

Language Variants and Styles

You can specify regional variants (e.g., British vs. American English) or specific typographic styles.

\setmainlanguage[variant=british]{english}
\setotherlanguage[spelling=old]{german}

\begin{document}
Today's date in the UK is: \today.

\begin{german}
This uses old German spelling rules.
\end{german}
\end{document}

Adjusting Numerals and Calendars

For some languages, you might want to use native digits instead of Western Arabic numerals.

\setotherlanguage[numerals=arabic]{arabic}
% This will use Eastern Arabic-Indic digits (١, ٢, ٣) 
% instead of Western digits (1, 2, 3) for that section.

Right-to-Left (RTL) Typography

Handling Right-to-Left (RTL) scripts like Arabic, Hebrew, or Persian used to be a nightmare in LaTeX. Polyglossia simplifies this significantly by automatically reversing the text direction when you switch to an RTL language.

Important Requirements for RTL:

Bidi Package: Polyglossia usually loads the bidi (bidirectional) package automatically.
Font Selection: You must assign a font that actually contains the characters for the RTL script.

\usepackage{polyglossia}
\setmainlanguage{english}
\setotherlanguage{arabic}

% You must have an Arabic font installed on your OS
\newfontfamily\arabicfont[Script=Arabic]{Amiri} 

\begin{document}
Standard English text goes from left to right.

\begin{arabic}
هذا نص باللغة العربية يتم محاذاته تلقائيًا إلى اليمين.
\end{arabic}

Back to English.
\end{document}

Warning: When working with RTL languages, ensure your LaTeX editor is set to UTF-8 encoding, or the characters may appear as gibberish in your source code.

Best Practices and Common Pitfalls

To ensure your multilingual documents compile smoothly and look professional, keep these tips in mind:

1. Always Define Fonts for Different Scripts

If you are using Greek, Cyrillic, or Arabic, Polyglossia looks for a font command named \<language>font. For example, if you load greek, you should define \newfontfamily\greekfont{...}. If you don't, LaTeX may fail to render the characters.

2. Choose the Right Engine

Polyglossia is heavily optimized for XeLaTeX. While it works with LuaLaTeX, some complex script features (especially for RTL) historically performed better in XeLaTeX. If you encounter weird spacing in Arabic, try switching your compiler to XeLaTeX.

3. Check for Package Compatibility

Some older packages that manipulate the header or TOC might conflict with Polyglossia's language switching. If your "Table of Contents" title isn't translating, ensure Polyglossia is loaded after most other structural packages.

4. Use "Script" and "Language" tags in Fontspec

When defining fonts for specific languages, use the features provided by the fontspec package to ensure OpenType features (like ligatures or localized glyph shapes) are activated.

\newfontfamily\russianfont[Script=Cyrillic, Language=Russian]{PT Serif}

Summary Checklist

Use XeLaTeX or LuaLaTeX.
Load fontspec before polyglossia.
Define your main language with \setmainlanguage{...}.
Define other languages with \setotherlanguage{...}.
Assign specific fonts to non-Latin scripts using \newfontfamily\<lang>font{...}.
Use environments for long blocks and \text<lang> for short snippets.

By mastering Polyglossia, you move beyond simple document preparation into the realm of professional, global typography, capable of producing beautiful documents in any language the world uses.

Understanding Polyglossia for Modern LaTeX

On this page