> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/languages/01-multilingual-typesetting-on-overleaf-using-polyglossia-and-fontspec.md). # Multilingual typesetting on Overleaf using polyglossia and fontspec ## Introduction This article provides an overview of typesetting multilingual documents on Overleaf using the XeLaTeX (or LuaLaTeX) compiler in conjunction with the `fontspec` and `polyglossia` LaTeX packages. For many, if not most, users their default choice of TeX engine is `pdfTeX`, which, unlike XeTeX and LuaTeX, does not have a built-in capability to read [UTF-8](https://en.wikipedia.org/wiki/UTF-8) encoded text files. Using pdfTeX makes typesetting certain languages in LaTeX very complicated, especially those that do not use a Latin-based script. Some packages—such as [`inputenc`, `fontenc` and](/latex/languages/05-arabic.md) [`arabtex`](/latex/languages/05-arabic.md)—provide support to pdfTeX for typesetting non-Latin languages and scripts, but not all glyphs and characters may be supported or rendered correctly in the output PDF, even if you’ve used the `utf8` or `utf8x` option with `inputenc`. For an in-depth discussion of UTF-8, Unicode encoding and the XeTeX/LuaTeX engines, the Overleaf article [Unicode, UTF-8 and multilingual text: An introduction](/latex/in-depth-articles/51-unicode-utf-8-and-multilingual-text-an-introduction.md) is a fascinating read. ## Enter XeTeX and LuaTeX The XeTeX and LuaTeX engines can directly read/process UTF-8 encoded text; consequently, they offer native support for Unicode—they can also [work with TrueType and OpenType fonts](/latex/fonts/03-xelatex.md) directly. These properties make them a natural choice for typesetting multilingual or non-Latin documents in LaTeX, producing outputs like these: ![](/files/PbmwpZCmagUzcWdFs6lq) ![](/files/TZ2sewg3YozfKYiAwTgM) ![](/files/SJRywX43524H1IoODyQ0) These examples can be found in the Overleaf Gallery: [How to Write Multilingual Text with Different Scripts in LaTeX on Overleaf](https://www.overleaf.com/latex/examples/how-to-write-multilingual-text-with-different-scripts-in-latex/wfdxqhcyyjxz) and [Multilingual "Thank-You"](https://www.overleaf.com/latex/templates/multilingual-thank-you/wjmrnnqkstyf). If you’re looking to typeset Chinese, Japanese and Korean, have a look at these articles: * [Chinese](/latex/languages/06-chinese.md) * [Japanese](/latex/languages/11-japanese.md) * [Korean](/latex/languages/12-korean.md) Xe(La)TeX is still useful for these languages, but more specialised TeX engines are available, specifically [designed for typesetting CJK languages](/latex/more-topics/45-tex-primitives-listed-by-cjk-tex-engine.md)—such as [pTeX](https://ctan.org/pkg/ptex?lang=en) for typesetting Japanese. Note that if your cursor seems to be misbehaving whilst editing text in certain languages on Overleaf, you may want to click on the Overleaf **Menu** button (situated above the project file list) and change the “Font Family” option. You could also try [changing your browser’s monospaced font preferences](https://www.howtogeek.com/208552/how-to-change-the-default-fonts-in-your-web-browser/) or using Overleaf’s Rich Text view instead. However, at the time of writing, the Source and Rich Text views may not (yet) fully support right-to-left text editing at the level of functionality we are aiming to achieve. ## Changing the project’s compiler The `fontspec` and `polyglossia` packages require the XeLaTeX or LuaLaTeX compiler, so you’ll need to set up your Overleaf project to use either of those compilers. Detailed instructions can be found in our article [Choosing a LaTeX Compiler](/latex/more-topics/08-choosing-a-latex-compiler.md) but here is a brief video clip showing how to set the compiler for your project: {% embed url="" %} Once you’re compiling with XeLaTeX or LuaLaTeX, you can (should) remove the `inputenc` and `fontenc` packages from your .tex file’s preamble because these Unicode-capable engines will assume input (text) files are UTF-8 encoded. Incidentally, all text files uploaded to Overleaf are converted to UTF-8 so you should usually use `utf8` with `inputenc` when working with the pdfLaTeX and LaTeX compilers on Overleaf. ## If your entire document involves just one language When using the `fontspec` package you might get away with only setting up a main (serif) font, a sans-serif font and probably a monospaced font designed to support the language you are typesetting—there’s a catch, but we’ll revisit that later in the article. For example, if your entire document is in Greek, with some English words, you can simply write ```latex \usepackage{fontspec} \setmainfont[Script=Greek]{GFS Artemisia} \setsansfont[Script=Greek]{GFS Neohellenic} \setmonofont[Script=Greek]{Noto Mono} . . . Το Lorem Ipsum είναι \textsf{απλά} ένα κείμενο χωρίς νόημα για τους επαγγελματίες της \texttt{τυπογραφίας} και στοιχειοθεσίας. ``` You can choose fonts from a [list of available TrueType and OpenType fonts](https://www.overleaf.com/help/193). The `Ligatures=TeX` option is added automatically for `\setmainfont` and `\setsansfont`, so you don’t have to add that yourself. (`\setromanfont` is an alias of `\setmainfont`.) The LaTeX code above produces the following output: ![](/files/yX9wZ6GghLykCDQm1N9l) ## Multiple languages/scripts in the same document: Introducing polyglossia If your document contains non-trivial amounts of text in multiple languages, the `polyglossia` package is helpful to help take care of language-specific typesetting conventions and hyphenation. ```latex \usepackage{fontspec} \setmainfont{FreeSerif} \setsansfont{FreeSans} \setmonofont{FreeMono} \usepackage{polyglossia} \setdefaultlanguage{french} \setotherlanguages{english,russian,thai} \begin{document} \begin{abstract} Le Lorem Ipsum est simplement du faux texte employé dans la composition et la mise en page avant impression. \end{abstract} Merci. \textenglish{Thank you.} \textrussian{Спасибо.} Et plus de texte en français! Le Lorem Ipsum est le faux texte standard ... \begin{english} Lorem Ipsum is simply dummy text ... \end{english} \begin{russian} Lorem Ipsum - это текст-`\textsf{рыба}', часто используемый в \texttt{печати} и вэб-дизайне. ... \end{russian} \begin{thai} \XeTeXlinebreaklocale "th_TH" \textenglish{Lorem Ipsum} คือ เนื้อหาจำลองแบบเรียบๆ ที่ใช้กันในธุรกิจงานพิมพ์หรืองานเรียงพิมพ์ \end{thai} ``` ![](/files/Nw4thYpfO9sJfrxI1uNl) `polyglossia` lets you set the main language of the document with `\setdefaultlanguage` (default is English) and (possibly multiple) ‘other’ languages with `\setotherlanguages`. (`\setmainlanguage` is an alias of `\setdefaultlanguage`.) If you expect to be using just one other foreign language you can use the singular `\setotherlanguage`. The language names are the same as those used by `babel`. We’ve prepared a small example of a (primarily) French document which also contains some English, Russian and Thai text. We’ve decided to use the FreeSerif, FreeSans and FreeMono typefaces. Because the document’s main language is `french`, the `abstract` environment automatically produces the heading ‘Résumé’. Notice how, at the end of the first paragraph, the exclamation mark is typeset using the French-spacing typesetting convention: it is set apart from ‘français’ even though it follows immediately after the word `français` in the source code. In the main text, short English, Cyrillic and Thai text snippets can be included in a paragraph of French text with `\textenglish{Thank you}`, `\textrussian{Спасибо}` and `\textthai{ขอบคุณ}`. Generally, you can use `\textLANGUAGE{...}` to typeset text in any `LANGUAGE` that has been declared by `\setdefaultlanguage` and `\setotherlanguages`. Because the document’s main (serif) font is FreeSerif, and FreeSerif contains glyphs for Latin, Cyrillic and Thai (and more!) scripts, `fontspec` and `polyglossia` can use it to render all these texts into the output PDF. For longer paragraphs of text in foreign/other languages, it is recommended to use `\begin{LANGUAGE}`...`\end{LANGUAGE}`, e.g. `\begin{russian}`...`\end{russian}`, `\begin{thai}`...`\end{thai}`. In the case of Arabic you can’t use `\begin{arabic}`...`\end{arabic}`; you’ll have to write `\begin{Arabic}`...`\end{Arabic}` instead, while `\textarabic{...}` is still valid. Some considerations may be needed for certain languages: for instance, within the `thai` environment, the words `Lorem Ipsum` need to be wrapped in a `\textenglish{...}` (or `\textfrench{...}`) command to ensure they are rendered using the Latin-script glyphs. At this point you might ask: If FreeSerif is so versatile and contains glyphs for Russian and Thai anyway, why would we still need to use `\textrussian`, `\begin{english}`...`\end{english}` etc? Wouldn’t that be redundant? Let’s see what happens when we remove the `\begin{english}`...`\end{english}` and `\begin{russian}`...`\end{russian}` environments: ![](/files/yyWgYnvX6Lj1NQwKcnAr) Certainly, the Latin and Cyrillic glyphs are all rendered in the output PDF, but note that some words are now hyphenated incorrectly: ‘unk-nown’ and ‘unchan-ged’—and стандартной isn’t hyphenated at all. Without the language-switching environments, the compiler thinks these text items are still in the French language and attempts to typeset them using French conventions. The compiler tries to apply French hyphenation rules which, naturally, produce incorrect results. This is why typography and typesetting is so much more than just font design and selection: they are very language- and culture-specific disciplines. Revisiting our first Greek example, we now see why it is a good idea to load `polyglossia` and use `\setdefaultlanguage{greek}`: to ensure the document is typeset following Greek conventions. ## Mixing right-to-left (RTL) and left-to-right (LTR) languages You need to be careful when typesetting a mixture of right-to-left (RTL) scripts, such as Arabic or Hebrew, and left-to-right (LTR) scripts in the same document. Consider the following small Arabic document with an English word, using Amiri as the main font: ```latex \usepackage{polyglossia} \setdefaultlanguage{arabic} \setmainfont{Amiri} \begin{document} ما هو differentiation \end{document} ``` which produces: ![](/files/WFXQ77qaDoYQ6g34IaKQ) The text is automatically set right-to-left, starting on the right-hand edge of the page. The word “differentiation” itself is typeset correctly as left-to-right text–but wait, *no it’s not*! It’s rendered as “dffirentiation” in the output! What’s going on? The Amiri font does have glyphs for Latin alphabets but here the text `differentiation` is not marked as English: the compiler treats `differentiation` as right-to-left text, as if it were a sequence of Arabic characters. During typesetting, the original sequence `iff` is processed as `ffi` (i.e., as RTL text) and Amiri’s [ligature](https://en.wikipedia.org/wiki/Typographic_ligature) glyph for “ffi” is typeset. Marking the word with `\textenglish{...}` ensures it is interpreted correctly as left-to-right text. ```latex \setmainfont{Amiri} \setotherlanguage{english} \newfontfamily\englishfont{TeX Gyre Termes} \begin{document} ما هو \textenglish{differentiation} ``` ![](/files/qVI2hGJSXDNaVVGfXFZE) **Note:** If you’re used to the `babel` package commands you’ll be happy to hear that the commands `\selectlanguage`, `\foreignlanguage` and the environment `otherlanguage` are also supported by `polyglossia`. ## Language-specific options Some languages support additional options for customisation; for example, `greek` accepts a `variant=ancient`, `mono` or `poly` option for ancient, monotonic or polytonic Greek; `hindi` can be configured with `numerals=western` or `devanagari`. See the [polyglossia package documentation](http://texdoc.net/pkg/polyglossia) for details. These can be specified when loading the language: ```latex \setdefaultlanguage[variant=poly]{greek} \setotherlanguage[numerals=western]{hindi} ``` or later at anytime: ```latex \setkeys{greek}{variant=ancient} ``` or even locally for a specific environment: ```latex \begin{greek}[variant=ancient] ... \end{greek} ``` ## Specifying fonts for specific languages You can specify the font used for different languages. Suppose you’d like to typeset all English text (contained in our previous example) in italics; you could write: ```latex \newfontfamily\englishfont{FreeSerif Italic} ``` ![](/files/yWIb9ClNX7gwHzqPzxwp) You can of course use something even more flamboyant: ```latex \newfontfamily\englishfont{Chancery Uralic} ``` ![](/files/CzxFFz7nt7H0jopxq0ax) This mechanism of setting fonts for different languages or scripts is especially important when you use a main font that *does not* have glyphs for all scripts or languages in your document. Suppose we now decide to use Caladea as the main document font: ```latex \setmainfont{Caladea} ``` Upon compilation we would see the following error: ``` Package polyglossia Error: The current roman font does not contain the Cyrillic script! (polyglossia) Please define \cyrillicfont with \newfontfamily. See the polyglossia package documentation for explanation. Type H for immediate help. ... l.15 \select@language {russian} Package polyglossia Error: The current roman font does not contain the Thai script! (polyglossia) Please define \thaifont with \newfontfamily. See the polyglossia package documentation for explanation. Type H for immediate help. ... l.23 \select@language {thai} ... ``` We are now obligated to specify which fonts to use for Cyrillic and Thai scripts. Again, you can refer to the [list of available TrueType and OpenType fonts](https://www.overleaf.com/help/193) on Overleaf. ```latex \newfontfamily\cyrillicfont[Script=Cyrillic]{Charis SIL} \newfontfamily\thaifont[Script=Thai]{Garuda} ``` ![](/files/LKy2ThOOn2OgZ44OIFXK) **Note**: it is outside the scope of this article to address issues relating to choices of aesthetically-pleasing and typographically-compatible font combinations. Notice that we’ve defined `\cyrillicfont` instead of `\russianfont`, i.e. we defined a font for the Cyrillic *script* rather than the Russian *language*. The advantage of defining `\cyrillicfont` is that if, for example, `serbian` is also a defined language in your project, then `\textserbian` would automatically use the defined `\cyrillicfont`. If you had defined only `\russianfont`, then using `\textserbian` would again complain about “the current roman font does not contain the Cyrillic script” and you would need to define `\cyrillicfont` anyway — *unless* you *did* mean to use a different font for Serbian text! Another similar scenario is the Devanagari *script*, which is used for the Hindi and Sanskrit *languages*; or the Arabic script used for Arabic and Farsi (Persian). ```latex \setdefaultlanguage{english} \setotherlanguages{hindi,sanskrit} \newfontfamily\devanagarifont[Script=Devanagari]{Lohit Devanagari} ... Hindi: \texthindi{हिन्दी} Sanskrit: \textsanskrit{संस्कृतम्} ``` ![](/files/XpONeUcG7y9d4DjqTVtE) When using `\newfontfamily` it is necessary to specify the `Script`, otherwise some glyphs may be rendered incorrectly; for example, if we had written only `\newfontfamily\thaifont{Garuda}` the typeset result may be wrong (left image below)—the correct output is produced by adding `[Script=Thai]`. Wrong: ![](/files/9eEG6AYYyixOGVNYvly0) Correct: ![](/files/rnFm1DfqHygcm0lcsmtp) ## Defining other font families Let’s have a look at another example, this time with Hebrew: ```latex \documentclass{article} \usepackage{polyglossia} \setdefaultlanguage[numerals=hebrew]{hebrew} \setotherlanguage{english} \newfontfamily\hebrewfont[Script=Hebrew]{Hadasim CLM} \begin{document} \section{מבוא} זוהי עובדה מבוססת שדעתו של הקורא תהיה מוסחת עלידי טקטס קריא כאשר הוא יביט בפריסתו. - \end{document} ``` ![](/files/vZXJC8eaefnKZerDAEMG) So far so good. Now suppose we were using a template originally created for an English document, which sets section headers in sans serif type using the `titlesec` package: ```latex \RequirePackage{titlesec} \titleformat{\section}{\Large\sffamily\bfseries}{\thesection}{1em}{} \usepackage{polyglossia} \setdefaultlanguage[numerals=hebrew]{hebrew} ... ``` We are confronted with the error message: ``` Package polyglossia Error: The current roman font does not contain the Hebrew script! (polyglossia) Please define \hebrewfont with \newfontfamily. See the polyglossia package documentation for explanation. Type H for immediate help. ... l.27 \section{מבוא} ``` This is a bit confusing: didn’t we already define `\hebrewfont` to be Hadasim CLM? Well, it’s really because we *haven’t specified a sans serif font for Hebrew*. Let’s remedy this by adding a definition for `\hebrewfontsf`: ```latex \newfontfamily\hebrewfontsf[Script=Hebrew]{Miriam CLM} ``` And now we have the output: ![](/files/eWtmxAhWJjHbSZvaZNUu) Should the need arise, we could also define a monospaced font to use with `\hebrewfonttt`. ## Acknowledgements All lorem ipsum snippets, in various languages, are from [`https://lipsum.com`](https://lipsum.com). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/latex/languages/01-multilingual-typesetting-on-overleaf-using-polyglossia-and-fontspec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.