-
Notifications
You must be signed in to change notification settings - Fork 34
/
Copy pathbabel.dtx
25516 lines (24527 loc) · 801 KB
/
babel.dtx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% \iffalse
% This document requires lualatex
%%
%% Copyright (C) 2012-2025 Javier Bezos and Johannes L. Braams.
%% Copyright (C) 1989-2012 Johannes L. Braams and
%% any individual authors listed elsewhere in this file.
%% All rights reserved.
%%
%%
%% This file is part of the Babel system.
%% --------------------------------------
%%
%% It may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
%% of this license or (at your option) any later version.
%% The latest version of this license is in
%% http://www.latex-project.org/lppl.txt
%% and version 1.3 or later is part of all distributions of LaTeX
%% version 2003/12/01 or later.
%%
%% This work has the LPPL maintenance status "maintained".
%%
%% The Current Maintainer of this work is Javier Bezos.
%%
%% The list of derived (unpacked) files belonging to the distribution
%% and covered by LPPL is defined by the unpacking scripts (with
%% extension |.ins|) which are part of the distribution.
%%
% \fi
%
% \CheckSum{5011}
%
% \iffalse
%<*filedriver>
\DocumentMetadata{
% testphase = {sec,toc,text},
lang = en-001,
}
\ProvidesFile{babel.dtx}%
[2025/03/10 v25.5
The multilingual framework for pdfLaTeX, LuaLaTeX and XeLaTeX]
\documentclass{ltxdoc}
\GetFileInfo{babel.dtx}
\usepackage{fontspec}
\setmainfont[
Scale=.88,
BoldFont = NotoSerif-Bold.ttf,
ItalicFont = NotoSerif-Italic.ttf,
BoldItalicFont = NotoSerif-BoldItalic.ttf]
{NotoSerif-Regular.ttf}
\setsansfont[
Scale=.88,
BoldFont = NotoSans-Bold.ttf,
ItalicFont = NotoSans-Italic.ttf,
BoldItalicFont = NotoSans-BoldItalic.ttf]
{NotoSans-Regular.ttf}
\setmonofont[Scale=.86, FakeStretch=.97]{DejaVu Sans Mono}
\raggedright
\setlength{\parindent}{.8em}
\frenchspacing
\addtolength{\oddsidemargin}{-2em}
\addtolength{\textwidth}{25.5pt}
\addtolength{\textheight}{3.5cm}
\addtolength{\topmargin}{-2cm}
\font\manual=logo10 % font used for the METAFONT logo, etc.
\newcommand*\MF{{\manual META}\-{\manual FONT}}
\newcommand*\babel{\textsf{babel}}
\newcommand*\Babel{\textsf{Babel}}
\newcommand*\xetex{\textsf{xetex}}
\newcommand*\pdftex{\textsf{pdftex}}
\newcommand*\luatex{\textsf{luatex}}
\newcommand\largetex{T\kern -.1517em\lower .45ex\hbox {E}\kern -.09emX}
\newcommand*\nb[1]{}
\newcommand*\m[1]{\mbox{$\langle$\normalfont\itshape#1\/$\rangle$}}
\newcommand*\langlist{%
\meta{language}\texttt{,}\meta{language}\texttt{,}...}
\newcommand*\langvar{\m{language}}
\newcommand*\Lopt[1]{\textsf{#1}}
\newcommand*\Lenv[1]{\texttt{#1}}
\newcommand*\menv[1]{\char`\{#1\char`\}}
\newcommand*\Eenv[1]{%
\quad...\quad
\texttt{\color{thered}\string\end\menv{#1}}}
\newcommand*\file[1]{\texttt{#1}}
\newcommand*\cls[1]{\texttt{#1}}
\newcommand*\pkg[1]{\texttt{#1}}
\setlength{\leftmargini}{1.5em}
\usepackage{framed}
\usepackage{multicol}
\usepackage{color,colortbl}
\usepackage[linkcolor=blue,urlcolor=blue,colorlinks=true]{hyperref}
\hypersetup{%
pdfsubject={LaTeX Multilingual documents and localization for pdfTeX,
LuaTeX and XeTeX.},
pdfauthor={Javier Bezos, Johannes Braams},
pdftitle={Babel},
pdfkeywords={TeX, LaTeX, pdfTeX, LuaTeX, XeTeX, internationalization,
localization}}
\ExplSyntaxOn
\normalmarginpar
\newcommand\New[1]{%
\regex_extract_once:nnN{(\d\d?)\.(\d\d?)}{#1}\bbltempa
\seq_pop_right:NN\bbltempa\bbltempb
\seq_pop_right:NN\bbltempa\bbltempa
\leavevmode%\marginpar
{\scriptsize
% \enspace
\colorbox[rgb]{.92, .86, .73}%
{%New~
#1%
\quark_if_no_value:NTF\bbltempb{}%
{~
\ifnum\bbltempa>2 \ifnum\bbltempb>34
\href{https://latex3.github.io/babel/news/%
whats-new-in-babel-\bbltempa.\bbltempb.html}%
{\scriptsize ※}%
\fi\fi
\ifnum\bbltempa>23
\href{https://latex3.github.io/babel/news/%
whats-new-in-babel-\bbltempa.\bbltempb.html}%
{\scriptsize ※}%
\fi}}}\enspace\ignorespaces}
\ExplSyntaxOff
\definecolor{thered}{rgb}{0.65,0.04,0.07}
\definecolor{thegrey}{gray}{0.8}
\definecolor{thegreyed}{gray}{0.6}
\definecolor{shadecolor}{rgb}{1,1,0.97}
\definecolor{messages}{rgb}{.66,.13,.27}
\makeatletter
\def\@seccntformat#1{%
\llap{\makebox[1.7cm][l]{\csname the#1\endcsname.}}%
\hspace{-.7cm}}
\def\@begintheorem#1#2{%
\list{}{}%
\global\advance\@listdepth\m@ne
\item[{\sffamily\bfseries\color{messages}\hspace*{1.4em}%\hspace*{2.8em}%
\MakeUppercase{#1}}]}%
\makeatother
\newtheorem{warning}{Warning}
\newtheorem{note}{Note}
\newtheorem{example}{Example}
\newtheorem{troubleshooting}{Troubleshooting}
\let\bblxv\verbatim
\let\bblexv\endverbatim
\newcommand\setengine{\def\engine}
\let\engine\relax
\begingroup
\catcode`\<=13
\catcode`\>=13
\catcode`\|=13
\AtBeginDocument{%
\gdef|{\verb|\def<##1>{$\langle${\rmfamily\itshape##1}$\rangle$}}}
\endgroup
\def\verbatim{%
\fboxsep=.8em
\begin{snugshade*}%
\ifx\engine\relax\else
\vskip-.75\baselineskip
\leavevmode\llap{%
\fboxsep=2pt\fbox{\scriptsize\textsc{\engine}}\hskip2.8em}%
\vskip-1.6\baselineskip
\vskip0pt
\global\let\engine\relax
\fi
\bblxv\vskip0pt }
\def\endverbatim{%
\bblexv\vskip-7.5ex \end{snugshade*}}
\catcode`\_=\active
\def_{\bgroup\let_\egroup\leavevmode\color{thered}}
\def\MacroFont{\fontencoding \encodingdefault \fontfamily\ttdefault
\fontseries\mddefault \fontshape\updefault \small \catcode`\_=\active}
\definecolor{shadecolor}{rgb}{0.96,0.96,0.93}
%
\makeatletter
\def\Describe#1#2{%
\@startsection{subsubsection}{100}{\z@}%
{2.5ex\@plus .7ex \@minus .2ex}%
{1.5ex \@plus .2ex}%
{\hspace{-2cm}\color{thegreyed}\normalsize\ttfamily}*%
{\underline{\strut{\color{thered}\string#1}\color{black}#2}}}
\def\DescribeOther{\addvspace{-1.5ex}\Describe}
\AtBeginDocument{\def\DescribeMacro#1{{\ttfamily\color{thered}\string#1}}}
\def\macro#1{% WIP
\if@noskipsec\leavevmode\vskip-1.2\baselineskip\vskip0pt\fi
\@startsection{paragraph}{101}{\z@}%
{3.25ex \@plus1ex \@minus.2ex}%
{-1em}%
{\sffamily\bfseries\color{thered}}*{\hspace*{-1em}\string#1}}
\let\environment\macro
\def\optstar{%
\kern1pt\relax
\colorbox{thegrey}{\ttfamily\hskip-.2em*\hskip-.2em}%
\kern1pt}
\def\trouble#1{\addcontentsline{tsh}{trouble}{#1}}
\def\toclevel@trouble{0}
\def\listoftroubles{\section*{Troubleshoooting}\@starttoc{tsh}}
\let\l@trouble\l@figure
\def\@tocrmarg{3.5em plus 1000em}
\let\saved@check@percent\check@percent
\let\check@percent\relax
% Changes to doc.sty (add <<...>> syntax)
\def\Module#1{%
\mod@math@codes$\langle${\color{thered}$\mathsf{#1}$}$\rangle$}
\begingroup
\catcode`\<\active
\catcode`\>\active
\gdef\check@plus@etc{%
\let\bbl@next\pm@module
\ifx*\next
\let\bbl@next\star@module
\else\ifx/\next
\let\bbl@next\slash@module
\else\ifx<\next
\let\bbl@next\var@module
\fi\fi\fi
\bbl@next}
\gdef\var@module#1#2#3>>{%
$\langle$\pm@module#2#3>$\rangle$%
\ifx*#2\ $\equiv$\fi}
\endgroup
\def\toc@usehook#1#2#3{%
\UseHookWithArguments{contentsline/#1}{4}%
{\toclevel@section}%
{#2}{#3}{\@contentsline@destination}}
\renewcommand*\l@section[2]{%
\ifnum\c@tocdepth>\z@
\addpenalty\@secpenalty
\addvspace{1.0em\@plus\p@}%
\setlength\@tempdima{2em}%
\begingroup
\parindent\z@ \rightskip\@pnumwidth
\parfillskip-\@pnumwidth
\leavevmode\bfseries
\advance\leftskip\@tempdima
\hskip-\leftskip
\toc@usehook{text/before}{#1}{#2}%
\csname contentsline@text@1@format\endcsname{#1}
\toc@usehook{text/after}{#1}{#2}%
\nobreak\hfil\nobreak \hb@xt@\@pnumwidth
{\hss
\toc@usehook{page/before}{#1}{#2}%
#2%
\toc@usehook{page/after}{#1}{#2}%
\kern-\p@\kern\p@}%
\par
\endgroup
\fi}
\renewcommand*\l@subsection{\@dottedtocline{2}{2em}{3em}}
\renewcommand*\l@subsubsection{\@dottedtocline{3}{5em}{4em}}
\renewcommand*\l@paragraph{\@dottedtocline{4}{9em}{4.5em}}
\renewcommand\partname{Part}
\def\@pnumwidth{3em}
\makeatother
\begin{document}
\title{Babel, a multilingual package for use with \LaTeX's standard
document classes.}
\author{Johannes Braams\\
Javier Bezos}
\date{Typeset \today}
\begin{titlepage}
\begin{minipage}[t][0pt]{30cm}
\vspace{-3cm}\hspace{-6cm}
\sffamily
\begin{tabular}{p{8cm}p{15cm}}
\cellcolor[rgb]{.86,.73,.67}
&\cellcolor[rgb]{.95,.95,.95}
\vspace{3.6cm}%
\color[rgb]{.55,.4,.35}
\leftskip5mm
\sffamily\fontsize{72}{72}\selectfont Babel
\vspace{1.8cm}
\\
\cellcolor[rgb]{.95,.95,.95}
\vspace{2cm}\hspace{1.5cm}
\begin{minipage}{5cm}
\Huge
\ifx\babelcode\undefined
User guide
\else
Code
\fi
\Large
\vspace{1.2cm}
Version \csname @gobble\expandafter\endcsname\fileversion\newline
\filedate
\LARGE
\vspace{1.2cm}
Javier Bezos\\[-.5ex]
{\large Current maintainer}
\vspace{.3cm}
Johannes L. Braams\\[-.5ex]
{\large Original author}
\end{minipage}
&\cellcolor[rgb]{.92, .86, .73}
\vspace{2cm}
\leftskip5mm
\begin{minipage}{10cm}
\fontsize{35}{45}\selectfont
\setlength\parskip{3mm}\raggedright
Localization and internationalization\\[1cm]
Unicode\\
\largetex\\
Lua\largetex\\
pdf\largetex\\
Xe\largetex
\vspace{20cm}
\end{minipage}
\end{tabular}
\end{minipage}
\end{titlepage}
\tableofcontents
\ifx\babelcode\undefined
\listoftroubles
\fi
\clearpage
\ifx\babelcode\undefined
\begin{description}
\item[\sffamily\color{messages}What is this document about?] This user
guide focuses on internationalization and localization with \LaTeX{}
and \pdftex, \luatex{} and \xetex{} with the \babel{} package. There
are also some notes on its use with e-Plain and pdf-Plain \TeX.
\item[\sffamily\color{messages}I only need learn the most basic
features.] The first subsections (1.1-1.6) describe the ways
of loading a language, which is usually all you need.
\item[\sffamily\color{messages}I don’t like manuals. I prefer sample
files.] This manual contains lots of examples and tips, but in GitHub
there are many
\href{https://github.com/latex3/babel/tree/master/samples}{sample
files}.
\item[\sffamily\color{messages}What if I’m interested only in the
latest changes?] Changes and new features with relation to version 3.8
are highlighted with \New{X.XX}\hspace{-.5em}
({\scriptsize ※} is a link to the \babel{} site), and there
are some notes for the latest versions in
\href{https://latex3.github.io/babel/}{the \babel{} site}. The most
recent features can still be unstable. Remember version 24.1 follows
3.99, because of a new numbering scheme.
\item[\sffamily\color{messages}Can I help?] Sure! You can follow the
development of \babel{} in
\href{https://github.com/latex3/babel}{GitHub} and make suggestions,
including requirements for some language or script. Feel free to fork
it and make pull requests. If you are the author of a package, send
me a few test files which I'll add to mine, so that possible issues can
be caught in the development phase.
\item[\sffamily\color{messages}It doesn't work for me!] You can ask for
help in some forums like \textsf{tex.stackexchange}, but if you have
found a bug, I strongly beg you to report it in
\href{https://github.com/latex3/babel/issues}{GitHub}, which is much
better than just complaining on an e-mail list or a web forum. Remember
\textit{warnings are not errors} by themselves, they just warn about
possible problems or incompatibilities. Hyphenation rules are
maintained separately
\href{https://github.com/hyphenation/tex-hyphen}{here}.
\item[\sffamily\color{messages}How can I contribute a new
language?] See section \ref{contribute} for contributing a language.
\item[\sffamily\color{messages}Where is the code?]
Run |lualatex --jobname=babel-code \let\babelcode\relax\input{babel.dtx}|.
\end{description}
\begin{note}
Now that the recommend engine for \LaTeX\ is \luatex, you can read
\href{https://latex3.github.io/babel/guides/migrating-pdftex-luatex.html}%
{Migrating from pdfTeX to LuaTeX} and
\href{https://latex3.github.io/babel/guides/migrating-xetex-luatex.html}%
{Migrating from XeTeX to LuaTeX}.
\end{note}
\section{The basic user interface}\label{U-I}
There are two ways to load a language with babel, namely, the old good
‘classical’ one, based on mostly self-contained declarations in a file
with |ldf| extension, and the ‘modern’ one, based on a brand new
mechanism based on descriptive |ini| files.
‘Classical’ doesn’t mean outdated or obsolete. In fact, this is the
recommended method in most languages where an |ldf| file exists. Below
is a list of the supported languages. See also
\href{https://latex3.github.io/%
babel/guides/which-method-for-which-language.html}{Which
method for which language} in the \babel{} site.
Basically, what you need is typically:
\begin{itemize}
\bfseries
\item Tell \babel{} which language or languages are required.
\item With non-Latin scripts and Unicode engines (\luatex\ is the
preferred one), select a suitable font (sec.~\ref{fonts})
\item In multilingual documents, switch the language in the text body
(sec.~\ref{selectors}).
\end{itemize}
You can find basic info and minimal \luatex{} example files for about
300 locales in the
\href{https://latex3.github.io/babel/guides/index-locale.html}{GitHub
repository}. There are also some videos on \href{https://www.youtube.com/playlist?list=PLVc2cHCI6zpJcaa1x-yK9iRjqtE3Ct2Ja}{Youtube}.
\subsection{Monolingual documents: the ‘classical’ way}
In most cases, a single language is required, and then all you need in
\LaTeX{} is to load the package using its standard mechanism for this
purpose, namely, passing that language as an optional argument. In
addition, you may want to set the font and input encodings.
Another approach is making the language a global option in order to let
other packages detect and use it. This is the standard way in \LaTeX{}
for an option – in this case a language – to be recognized by several
packages (in other words, \babel{} doesn’t set the languages, it just
recognizes the options passed to the class or the package).
Many languages are compatible with \textsf{luatex} and \textsf{xetex},
but a few only work with \pdftex. When these engines are used, the
Latin script is covered by default in current \LaTeX{} (provided the
document encoding is UTF-8). Other scripts require loading
\textsf{fontspec}, although \babel{} provides a higher level interface
(see |\babelfont| below).
\begin{example}
Here is a simple full example for “traditional” \TeX{} engines (see
below for \luatex{} and \xetex{}). The package |fontenc| does not
belong to \babel, but it is included in the example because typically
you will need it. It assumes UTF-8, the default encoding:
\setengine{pdftex}
\begin{verbatim}
\documentclass{article}
\usepackage[T1]{fontenc}
_\usepackage[french]{babel}_
\begin{document}
Plus ça change, plus c'est la même chose!
\end{document}
\end{verbatim}
Now consider something like:
\begin{verbatim}
_\documentclass[french]{article}_
\usepackage{babel}
\usepackage{varioref}
\end{verbatim}
With this setting, the package \texttt{varioref} will also see
the option |french| and will be able to use it.
\end{example}
\begin{example}
Now a simple monolingual document in Russian (text from the Wikipedia)
with \luatex{} or \xetex{}. Note neither \textsf{fontenc} nor
\textsf{inputenc} is necessary, and a so-called Unicode font must be
loaded (in this example with the help of |\babelfont|, described below).
\setengine{luatex/xetex}
\begin{verbatim}
_\documentclass[russian]{article}_
\usepackage{babel}
_\babelfont{rm}{DejaVu Serif}_
\begin{document}
Россия, находящаяся на пересечении множества культур, а также
с учётом многонационального характера её населения, — отличается
высокой степенью этнокультурного многообразия и способностью к
межкультурному диалогу.
\end{document}
\end{verbatim}
\end{example}
\begin{note}
Because of the way \babel{} has evolved, ``language'' can refer to
(1) a set of hyphenation patterns as preloaded into the format, (2) a
package option, (3) an |ldf| file, and (4) a name used in the
document to select a language. Please, read the documentation for
specific languages for further info.
\end{note}
\begin{note}
\Babel{} does not make any readjustments by default in font size,
vertical positioning or line height. This is on purpose
because the optimal solution depends on the document layout and the
font, and very likely the most appropriate one is a combination of
these settings.
\end{note}
\begin{note}
Although it has been customary to recommend placing |\title|,
|\author| and other elements printed by |\maketitle| after
|\begin{document}|, mainly because of shorthands, it is advisable to
keep them in the preamble. Currently there is no real need to use
shorthands in those macros.
\end{note}
\begin{note}
With \textsf{hyperref} you may want to set the PDF document language
with something like:
\begin{verbatim}
\usepackage[_pdflang=es-MX_]{hyperref}
\end{verbatim}
This is not currently done by \babel{} and you must set it by hand. The
PDF document language can also be set with |\DocumentMetadata|, before
|\documentclass|; for example:
\begin{verbatim}
\DocumentMetadata{_lang=es-MX_}
\end{verbatim}
\end{note}
\begin{warning}
In the preamble, \textit{no} language has been selected, except
hyphenation patterns and the name assigned to |\localename| (and
|\languagename|) (in particular, shorthands, captions and date are not
activated). If you need to define boxes and the like in the preamble,
you might want to use some of the language selectors described below.
\end{warning}
\begin{troubleshooting}
\trouble{Package inputenc Error: Invalid UTF-8 byte ...}
\textit{Package inputenc Error: Invalid UTF-8 byte ...}
A common source of trouble is a wrong setting of the input encoding.
Make sure you set the encoding actually used by your editor, or
even better, make sure the encoding in your editor is set to UTF-8.
\end{troubleshooting}
\begin{troubleshooting}
Another typical error when using \babel{} is the following:
\trouble{Unknown language 'LANG'}
\begin{verbatim}
! Package babel Error: Unknown language 'LANG'. Either you have
(babel) misspelled its name, it has not been installed,
(babel) or you requested it in a previous run. Fix its name,
(babel) install it or just rerun the file, respectively. In
(babel) some cases, you may need to remove the aux file
\end{verbatim}
The most frequent reason is, by far, the latest (for example, you
included |spanish|, but you realized this language is not used after
all, and therefore you removed it from the option list). In most
cases, the error vanishes when the document is typeset again, but in
more severe ones you will need to remove the |aux| file.
\end{troubleshooting}
\begin{troubleshooting}
\textit{No hyphenation patterns were preloaded...}
The following warning is about hyphenation patterns, which are
not under the direct control of \babel:
\trouble{No hyphenation patterns were preloaded for (babel) the
language 'LANG' into the format}
\begin{verbatim}
Package babel Warning: No hyphenation patterns were preloaded for
(babel) the language `LANG' into the format.
(babel) Please, configure your TeX system to add them and
(babel) rebuild the format. Now I will use the patterns
(babel) preloaded for \language=0 instead on input line 57.
\end{verbatim}
The document will be typeset, but very likely the text will not be
correctly hyphenated. Some languages in some system may be raising
this warning wrongly (because they are not hyphenated) -- just ignore
it. See the manual of your distribution (Mac\TeX, Mik\TeX, \TeX Live,
etc.)\ for further info about how to configure it.
\end{troubleshooting}
\begin{troubleshooting}
\textit{You are loading directly a language style.}
Loading directly
|sty| files in \LaTeX{} (i.e., |\usepackage{<language>}|) was deprecated
many years ago and you will get the error: \trouble{You are loading
directly a language style}
\begin{verbatim}
! Package babel Error: You are loading directly a language style.
(babel) This syntax is deprecated and you must use
(babel) \usepackage[language]{babel}.
\end{verbatim}
\end{troubleshooting}
\begin{note}
You will see an ‘info’ in the log file stating some data is being
loaded from an |ini| file. It includes standardized names for
language and script used by |\babelfont|, and the BCP 47 tag, required in
some cases by |\Make<Xxxxx>case|.
\end{note}
\subsection{Monolingual documents: the ‘modern’ way}
When, for whatever reason, the ‘classical’ way with the |ldf| is not
suitable for the needs of a document or a document system, you have to
resort to a different mechanism, which is activated with the package
option |provide=*| (in monolingual documents).
\begin{example}
Although Georgian has its own \texttt{ldf} file, here is how to
declare this language in Unicode engines. Here, as in a previous
example, we resort to |\babelfont| to set the font for this language
(with the |Harfbuzz| renderer, just to show how to set it, because
here the |Node| renderer should be fine).
\setengine{luatex/xetex}
\begin{verbatim}
\documentclass{book}
\usepackage[_georgian, provide=*_]{babel}
_\babelfont{rm}[Renderer=Harfbuzz]{DejaVu Sans}_
\begin{document}
\tableofcontents
\chapter{სამზარეულო და სუფრის ტრადიციები}
ქართული ტრადიციული სამზარეულო ერთ-ერთი უმდიდრესია მთელ მსოფლიოში.
\end{document}
\end{verbatim}
And with a global option:
\begin{verbatim}
\documentclass[_georgian_]{book}
\usepackage[_provide=*_]{babel}
\babelfont{rm}[Renderer=Harfbuzz]{DejaVu Sans}
\end{verbatim}
\end{example}
\begin{note}
This option actually loads the language with |\babelprovide| and the
|import| option, described below. Instead of an asterisk, you may
provide a list of options for |\babelprovide| enclosed in braces
(|import| is included by default).
\end{note}
\begin{example}
For a text in Chinese, you can write in the preamble:
\setengine{luatex/xetex}
\begin{verbatim}
\usepackage[_chinese, provide=*_]{babel}
_\babelfont{rm}{FandolSong}_
\end{verbatim}
The skip between characters is 0 pt plus .1 pt, which can be modified
with an option (explained below) in |provide|. For example:
\setengine{luatex/xetex}
\begin{verbatim}
\usepackage[chinese, provide=_{ intraspace=0 .2 0 }_]{babel}
\end{verbatim}
\end{example}
\subsection{Mostly monolingual documents: lazy loading}
\label{mostlymono}
\New{3.39} Very often, multilingual documents consist of a main
language with small pieces of text in another languages (words, idioms,
short sentences). Typically, all you need is to set the line breaking
rules and, perhaps, the font. In such a case, there is no need to
clutter the preamble (particularly the class and package options)
because \babel{} does not require declaring these secondary languages
explicitly — the basic settings are loaded on the fly when the language
is first selected.
This is particularly useful in documents with many languages, and also
when there are short texts of this kind coming from an external source
whose contents are not known beforehand (for example, titles in a
bibliography). In this regard, it is worth remembering that
|\babelfont| does \textit{not} load any font until required, so that it
can be used just in case.
\New{3.84} With \pdftex, when a language is loaded on the fly
(internally it's loaded with |\babelprovide|) selectors now set the
font encoding based on the list provided when loading |fontenc|. Not
all scripts have an associated encoding, so this feature works only
with Latin, Cyrillic, Greek, Arabic, Hebrew, Cherokee, Armenian, and
Georgian, provided a suitable font is found.
\begin{example}
A trivial document with the default font in English and Spanish, and
FreeSerif in Russian is:
\setengine{luatex/xetex}
\begin{verbatim}
\documentclass[english]{article}
\usepackage{babel}
_\babelfont[russian]{rm}{FreeSerif}_
\begin{document}
English. _\foreignlanguage{russian}{Русский}_.
_\foreignlanguage{spanish}{Español}_.
\end{document}
\end{verbatim}
If you need the ‘modern’ way to load the main language set as global
option, just write:
\begin{verbatim}
\usepackage[provide=*]{babel}
\end{verbatim}
\end{example}
\begin{note}
Instead of its name, you may prefer to select the language with the
corresponding BCP 47 tag. This alternative, however, must be activated
explicitly, because a two- or three-letter word is a valid name for a
language (e.g., |lu| can be the locale name with tag |khb| or the tag
for |lubakatanga|). See section \ref{bcp47} for further details.
\end{note}
\subsection{Multilingual documents: the ‘classical’ way}
In multilingual documents, just use a list of the required languages
either as package or as class options. The last language is considered the
main one, activated by default. Sometimes, the main language changes
the document layout (e.g., |spanish| and |french|).
To switch the language there are two basic macros, described below in
detail: |\selectlanguage| is used for blocks of text, while
|\foreignlanguage| is for chunks of text inside paragraphs.
\begin{example}
In \LaTeX, the preamble of the document:
\begin{verbatim}
\documentclass{article}
\usepackage[dutch,english]{babel}
\end{verbatim}
would tell \LaTeX{} that the document would be written in two
languages, Dutch and English, and that English would be the first
language in use, and the main one.
\end{example}
\begin{example}
A full bilingual document with \pdftex{} follows. The main language is
|french|, which is activated when the document begins. It assumes UTF-8:
\setengine{pdftex}
\begin{verbatim}
\documentclass{article}
\usepackage[T1]{fontenc}
_\usepackage[english,french]{babel}_
\begin{document}
Plus ça change, plus c'est la même chose!
_\selectlanguage{english}_
And an English paragraph, with a short text in
_\foreignlanguage{french}{français}_.
\end{document}
\end{verbatim}
\end{example}
\begin{example}
With \luatex{} and \xetex, the following bilingual, single script
document in UTF-8 encoding just prints a couple of ‘captions’ and
|\today| in Danish and Vietnamese. No additional packages are
required, because the default font supports both languages.
\setengine{luatex/xetex}
\begin{verbatim}
\documentclass{article}
_\usepackage[vietnamese,danish]{babel}_
\begin{document}
Danish: \prefacename, \alsoname, \today.
\selectlanguage{vietnamese}
Vietnamese: \prefacename, \alsoname, \today.
\end{document}
\end{verbatim}
\end{example}
\begin{note}
Although strongly discouraged, languages can be set as global and as
package option at the same time, but in such a case you should set
explicitly the main language with the package option |main|,
described below:
\begin{verbatim}
\documentclass[_italian_]{book}
\usepackage[ngerman,_main=italian_]{babel}
\end{verbatim}
\end{note}
\begin{note}
Once a language is loaded, you can select it with the corresponding
BCP 47 tag. See section \ref{bcp47} for further details.
\end{note}
\begin{note}
Documents with several input encodings are not frequent, but
sometimes are useful. You can set different encodings for different
languages as the following example shows:
\begin{verbatim}
\addto\extrasfrench{\inputencoding{latin1}}
\addto\extrasrussian{\inputencoding{koi8-r}}
\end{verbatim}
\end{note}
\subsection{Multilingual documents: the ‘modern’ way}
If lazy loading is not enough for your purposes, you can still tell
which languages should be loaded as either class or package options.
You can combine the ‘classical’ and the ‘modern’ ways with three
options to set which method you want, which cover the most typical
cases:
\begin{itemize}
\item |provide=*| is the option explained above for monolingual
documents. If there are more languages, it applies only to the main
language, while the rest will be loaded in the ‘classical’ way.
\item |provide+=*| loads the main language in the ‘classical’ way,
and the rest in the ‘modern’ one.
\item |provide*=*| is the same for all languages, i.e., main and
secondary ones are loaded in the ‘modern’ way.
\end{itemize}
More complex combinations can be handled with |\babelprovide|,
explained below.
\begin{example}
Your document is written in Thai with large chunks in Dutch and German,
and you want the |ldf| files in the latter because, for example, you
need their shorthands. The font is Norasi, which covers the three
languages:
\setengine{luatex/xetex}
\begin{verbatim}
\usepackage[dutch,ngerman,thai,_provide=*_]{babel}
\babelfont{rm}{Norasi}
\end{verbatim}
This will load |dutch| and |ngerman| in the classical |ldf| mode, but
|thai| in the modern |ini| mode. Other options are:
\begin{verbatim}
\usepackage[dutch,ngerman,thai]{babel}
\end{verbatim}
which will use the classical mode for in languages (as decribed in the
previous section, but note |thai.ldf| is not supported in Unicode
engines), and:
\begin{verbatim}
\usepackage[dutch,german,thai,_provide*=*_]{babel}
\end{verbatim}
which will use the modern mode in all languages (note the correct name
here is |german|. (The option
|\usepackage||[dutch,ngerman,thai,provide+=*]||{babel}| doesn’t make
much sense in this case.)
\end{example}
\subsection{Languages supported by \babel{} in the ‘classical’ mode}
(To be updated.) In the following table most of the languages supported
by \babel{} with an |ldf| file are listed, together with the names of
the options which you can load \babel\ with for each language. Note this
list is open and the current options may be different. It does not
include |ini| files (see below).
Except in a few cases (e.g., |ngerman|, |serbianc|, |acadian|) names are
those of the Unicode CLDR (or based on them).
Most of them work out of the box, but some may require extra fonts,
encoding files, a preprocessor or even a complete framework (like
\textsf{CJK} or \textsf{luatexja}).
\begingroup
\bigskip\hrule\nobreak
\makeatletter
\newcommand\tag[3][?]{\par
\hspace{-2em}\textcolor{thered}{\texttt{#2}}#3\enspace
\ifx\relax#1\relax\else
\ifx?#1%
\href{https://ctan.org/pkg/babel-#2}{\scriptsize ※}%
\else
\href{https://ctan.org/pkg/#1}{\scriptsize ※}%
\fi
\fi}
\def\subtag#1#2{\par
\hspace{-1em}\texttt{#1}#2\enspace}
\def\subtagalt#1#2{\par
\hspace{-1em}\textcolor{thered}{\texttt{#1}}#2\enspace}
\def\tagmin#1#2{\par
\hspace{-2em}\textcolor[gray]{.4}{\texttt{#1}}#2\enspace}
\def\subtagmin#1#2{\par
\hspace{-1em}\textcolor[gray]{.4}{\texttt{#1}}#2\enspace}
\def\note#1{\par{\footnotesize#1\par}}
\small
\bigskip
\textit{This list is still under revision.}\\
Recommended names are set in \textcolor{thered}{red}.\\
Additional languages are set in \textcolor[gray]{.4}{gray}.\\
Discouraged and deprecated names are not included.\\
There are some notes in a few languages.\\
The reference mark ({\scriptsize ※}) is a link to CTAN.
\bigskip\hrule\nobreak
\begin{multicols}{2}
\leftskip2em\parindent0pt
\tag[babel-dutch]{afrikaans}{}
\tag{albanian}{}
\tag[arabi]{arabic}{}
\note{Requires \textsf{arabi}.}
\tag{azerbaijani}{}
\tag{basque}{}
\tag{belarusian}{}
\tag{bosnian}{}
\tag{breton}{}
\tag{bulgarian}{}
\tag{catalan}{}
\tag{croatian}{}
\tag{czech}{}
\tag{danish}{}
\tag{dutch}{}
\tag{english}{}
\subtagalt{american}{}
\subtag{USenglish}{}{}
\subtagalt{australian}{}
\subtagalt{british}{}
\subtag{UKenglish}{}
\subtagalt{canadian}{}
\subtagalt{newzealand}{}
\tag{esperanto}{}
\tag{estonian}{}
\tagmin{ethiop}{} %%%%%%
\tag[arabi]{farsi}{}
\note{Requires \textsf{arabi}.}
\tag{finnish}{}
\tag{french}{}
\subtagalt{acadian}{}
\tag[babel-friulan]{friulian}{}
\tag{galician}{}
\tag{georgian}{}
\tag{german}{}
\note{This block refers to the old ortography. For the modern one, use
the names in the block \textsf{ngerman}.}
\subtagalt{austrian}{}
\subtagalt{swissgerman}{}
\note{Swiss High German}
\tag{greek}{}
% \subtagalt{polutonicogreek}{}
\subtagmin{ibycus}{}
\subtagmin{bgreek}{}
\tag{hebrew}{}
\tag[devanagari]{hindi}{}
\note{Requires \textsf{velthuis}.}
\tag{hungarian}{}
\subtag{magyar}{}
\tag{icelandic}{}
\tag{indonesian}{}
\tag{interlingua}{}
\tag{irish}{}
\tag{italian}{}
\tag{japanese}{}
\tag{kurmanji}{}
\tag{latin}{}
% \subtagalt{classiclatin}{}
% \subtagalt{medievallatin}{}
% \subtagalt{ecclesiasticlatin}{}
\tag{latvian}{}
\tag{lithuanian}{}
\tag[babel-sorbian]{lowersorbian}{}
\tag{macedonian}{}
\tag{malay}{}
\tag[mongolian-babel]{mongolian}{}
\tag[babel-german]{ngerman}{}
\note{This block refers to the new ortography.}
\subtagalt{naustrian}{}
\subtagalt{nswissgerman}{}
\note{Swiss High German}
\tag[babel-samin]{northernsami}{}
\tag[babel-norsk]{norwegian}{}
\subtag{norsk}{}
\tag[babel-norsk]{nynorsk}{}
\tag{occitan}{}
\tag{piedmontese}{}
\tagmin{pinyin}{}
\tag{polish}{}
\tag[babel-portuges]{portuguese}{}
\subtagalt{brazilian}{}
\tag{romanian}{}
\tag{romansh}{}
\tag{russian}{}
\tag[babel-scottish]{scottishgaelic}{}
\subtag{scottish}{}
\tag{serbianc}{}
\note{Cyrillic script}
\subtagalt{serbian}{}
\note{Latin script}
\tag{slovak}{}