Language options in \DocumentMetadata

[jbezos]

There are currently to ways to set the main locale for a document, as shown:

\DocumentMetadata{lang=ga}

and

\documentclass[irish]{article}

(Or a package option, but in the examples I only use class options.)

They should be coordinated somehow. Let’s consider several scenarios.

---

\DocumentMetadata{}
\documentclass[irish]{article}

Here we can pass lang=ga to \DocumentMetadata, which is more or less obvious. Loading multiple languages as options also has a straightforward interpretation.

---

\DocumentMetadata{lang=ga}
\documentclass{article}

But \usepackage{babel} is currently valid even if there is no class option, so this will be an incompatible change. Furthermore, packages declaring macros for the irish option won’t recognize the language.

---

\DocumentMetadata{lang=ga}
\documentclass[irish]{article}

Redundant, but it makes sense. On the other hand...

---

\DocumentMetadata{lang=ga}
\documentclass[english]{article}

Is this a contradiction, or perhaps is irish the main language and english a secondary one?

---

\DocumentMetadata{lang=ga}
\documentclass[english,irish]{article}

It makes sense. But...

---

\DocumentMetadata{lang=ga}
\documentclass[irish,english]{article}

Again, what does this mean? Should it just be forbidden?

[u-fischer]

We have to set the main language in the PDF and for this we must have in the kernel an documented interface that works without some external packages.

This interface is \DocumentMetadata{lang=ga}.

So the question is what this means for a package like babel.

A package like babel can both detect if a language has been set in \DocumentMetadata and to which value.

If no language has been set, babel could issue a \keys_define:nn { document / metadata }{lang=ga} to fill the gap.

If a language has been set, then babel should probably assume that the user explicitly wanted this language as main language. What babel does with this info is then imho up-to you. If babel detects a clash with its own main language it could issue a warning. It could also use the language as main language, for example if the user didn't explicity set a main language with a main option or only loaded \usepackage{babel}.

Personally I never use class options for languages, but use \usepackage[ngerman]{babel},
and I would be happy if

\DocumentMetadata{lang=de}
...
\usepackage{babel}

had the same effect.

[FrankMittelbach]

Perhaps we should look at this from a different angle.

Tasks

I see four somewhat related tasks that need to be done/specified:

• set the meta data of the document and here in particular the
  document language (which unfortunately has to be a document-wide
  single value)

• declare all languages used within the document (to set up proper
  support for them)

• specify the language(s) to be used for "navigational" things in the
  document, e.g., names for TOC, Chapter and the like. For most
  documents that's a single language but in multi-lingual documents
  that may not be the case or may change for parts of a single
  document

• specify the typesetting language to start the document with

Compatibility behavior

I think there are different possible approaches. Again there are some
scenarios that need to be considered.

• Existing document using current way babel handles language. If this
  document is updated to become accessible, i.e., there is a
  \DocumentMetada{...} declaration added, what should happen?

• New document: what is the recommended specification method that
  might give better results than a simple compatibility approach that
  tries to do the best out of a given specification?

Suggested conclusions / thoughts

Document meta data

This is something that has to happen in \DocumentMetadata and not on
a package level because it has to happen always regardless of which
other support package (or packages) gets loaded.

This language is naturally also one of the languages that are used by
the document, so it should be taken in consideration when setting all
document languages up.

Not sure it does right now, but \DocumentMetadata should flag its
language in case it is English without being explicitly given because
that might influence how, say, babel set things up if there is a
conflicting global setting, etc.

Given the (few) dozen traditional language names in LaTeX one could
think of providing the one corresponding with the lang= value to the
global option list for the class (unless none was given) so that it is
available to any package when loaded. The advantage is that this would
keep their mechanisms working as before without the need for
adjustments. But I'm not sure it is a good idea.

Languages used by the document

In my opinion this is best done on the level of babel, either as
options to the package or as a declaration through one of the other
babel interfaces. Of course, the global option approach can be
supported for this though I'm not sure it is a good approach going forward.

I guess my recommendation for new documents would be to either

• not use global options as a user

• or just the main language to configure other legacy packages such
  as varioref and the like

and have all other languages specified on the level of babel.

Main language used in the document (if there is only one)

My proposal is that this the lang= value from \DocumentMetadata if
that is specified. This could be compared to the languages specified
as belonging to the document. Several strategies are possible, but
here is one (perhaps there are better ones).

With babel-last I denote the language that babel traditionally
recognized as the main language, i.e., the last in the option list.
The language specified in \DocumentMetadata is denoted by
meta-lang.

• if there is no babel-last then meta-lang is the main document
  language

• if meta-lang = babel-last we are good

• if meta-lang is explicitly given (and not a infered as being "en")
  and it differs from babel-last then accept meta-lang as the main
  language (maybe with a warning but probably not) and use babel-last
  just as the starting language in the document.

• if meta-lang is not given (and so implicitly set to "en") that
  should be detected there should be a warning. Only in that case
  use babel-main even though that then conflicts with the meta
  value. This is really an emergency measure to get going and get
  some more or less reasonable results albeit with wrong meta data.

The above algorithm works nicely for both old and new documents in my
opinion.

Main language used in the document (if there are more than one)

Same as before, except that in the document you change from one "main"
language to another using babel mechanisms, so nothing new really.

Starting language at the beginning of the document

If given use babel-last as the starting language, otherwise use
meta-lang as the starting language.

Observations

• There has to be a way for babel to receive meta-lang and to
  identify whether it is an explicitly specified language or just a
  default ("en") because nothing was explicitly specified

• One could consider populating the global option list with a LaTeX
  language name based on meta-lang, Not sure this is a good idea, but
  if, it could be done automatically by \documentclass including
  checking that it isn't already explicitly given in the option list
  by the user

• ... the document is already far to long, so I stop for comments

[cfr42]

Probably this is obvious, but ...

Currently things work correctly if all languages are given as global options and/or all languages as babel options. However, things break if multiple languages are used as babel options and only the main language is specified globally. (Where 'break' means 'does not behave as I expect'.)

Some packages pick up multiple languages from the global options list e.g. glossaries tries to load language configurations for all those specified and not just the main language.

[jbezos]

@cfr42 A good point. I’m considering several combinations and this one is certainly relevant. Actually, ‘does not behave as I expect’ is ‘behavior is not well defined’. This is a good opportunity to define a consistent behavior, even with some breaking change. That’s why I’m thinking about it a lot.

[jbezos]

There is now some experimental code, explained here: https://latex3.github.io/babel/news/whats-new-in-babel-25.8.html.

Pending is how to deal with localized classes and packages via class options, even if babel is not loaded. This belongs to the LaTeX core. For example:

\DocumentMetadata{lang=ca}
\documentclass[catalan]{<mylocalizedclass>}

vs.

\DocumentMetadata{lang=ca}
\documentclass{<mylocalizedclass>}

Here, <mylocalizedclass> contains \DeclareOption{catalan}{...}, \DeclareOption{english}{...}, \DeclareOption{french}{...}m \DeclareOption{spanish}{...}, etc.