Re: translated manuals output file and directory name/location

On Thu, Aug 06, 2026 at 09:35:19PM +0100, Gavin Smith wrote:
> I strongly prefer an "XPG locale" (I understand this as a locale identifier
> looking like "en_US") to a BCP47 language tag.  We should use the same
> identifiers used for gettext translations, e.g. pt and pt_BR.  These

Both "XPG locale" and BCP47 language tag are like "en_US" and pt_BR
(though BCP47 is in general like en-US, the CLDR based Language
Identifier, which are almost the same as BCP47 use _, like "en_US").
There are only differences between "XPG locale" and BCP47 language tag
when scripts and variants are considered.

> Document scripts or language dialects will much less often be an issue,
> but these can be accommodated in the "variant" suffix, if the identifier
> is of the form LL[_CC]@VARIANT.
> 
> gettext documentation changed (in May 2026) to accommodate the possibility
> of specifying a dialect with a variant suffix:
> 
> Script and language variant have been both described in the same suffix.
> An example of this is "sr@ijekavianlatin" to represent the Serbian language,
> written with the Latin script, Ijekavian dialect.  I'm not sure if there
> is any process for defining the sames of such variants, other than common
> usage by a user community.  Presumably the gnulib bcp47 module (which
> we use) can be adapted if getting the locale name is ever a problem.

The two issues I see with the XPG locale is that the @VARIANT is
under-specified and there is no clear way to have a script and a variant
(or several variants), while the BCP47 tags are well specified.  But we
can use XPG locale nonetheless.

> This is all assuming that we need to use such directories in Texinfo for
> Info files with specified languages, for more on which see below.

If directories are not used, but file names are used, there is still a
need for interpretation of the LL language tag.

> > * The manuals are installed in a LL subdirectory by install-info, LL being
> >   based on @documentlanguage, @documentscript and
> >   @documentlanguagevariant as described in the previous point.  The
> >   manual information is added to the dir file in this subdirectory.
> > 
> >   The user could add such directories to INFOPATH manually.
> 
> We need to be careful about compatibility between installation location
> and Info-reading program.  I don't see how we can install manuals under
> LL subdirectories when existing Info readers don't know to look for them
> there.  This is among the points that Eli raised.

That is why I wanted to have some anticipation, such that the Info
readers can be modified in advance and be ready when manuals start being
installed in the directories.

> I think it is fine to have them all in the same infodir, with not much
> downside if any.

It is simple, but I think that it does not scale well, if all the
manuals have more than 20 translations, the dir will be quite crowded.

> In short, I see no benefit to the changes being proposed.  It appears to
> be creating a lot of work for no reason.
> 
> It is possible that GNU/Linux distributions could make changes to put the
> Info files in subdirectories, or that Automake build systems would change
> to make this happen.  I don't think we should change the default behaviour
> of install-info to read a language from the Info file to get the name of
> a directory to install the file in, as this would be backwards incompatible
> and would lead to users being unable to find Info manuals.
> 
> One idea is to add an option to install-info to enable such behaviour, which
> could be used by users if they want it, although this would need further
> consideration.

This needs to be coordinated with Info readers, hence the proposal to
have a design such that Info readers can be modified in anticipation of
using directories per language.

> Using the contents of LANGUAGE could be a good idea in case Info manuals
> start being installed in language directories in the future.  But I don't
> know how commonly used LANGUAGE is by users, or if they would be likely
> to set it.
> 
> I was looking at how manpages translations are handled.  On my system,
> there are language directories under "/usr/share/man".  (For example,
> "/usr/share/man/de/man1/cups.1.gz" is the "cups(1)" man page in German.)
> However, it doesn't appear to be possible to access them with the "man"
> command without having the locale installed for that language, e.g. if
> I run "LANG=de man cups" I get an error message:
> 
> man: can't set the locale; make sure $LC_* and $LANG are correct
> 
> - as I don't have a locale de_DE etc. installed.
> 
> Not sure if that is a model worth imitating or not.  It would be useful
> to find out what the experiences of readers of non-English manuals was.

That is more or less what I propose, and there is both the possibility
to use th elocale or th ecommand-line.

> > Changes to be done to texi2any:
> > 
> > when generating the Info file, the @documentlanguage, @documentscript
> > and @documentlanguagevariant information should be made available in the
> > Info file.  I propose to use the same method as the one used to convey
> > that information to Info readers that output translated strings.  Given
> > the previous discussion:
> >   https://lists.gnu.org/archive/html/bug-texinfo/2026-05/msg00009.html
> > this should be through variables, Info-documentlanguage,
> > Info-documentscript (and Info-documentlanguagevariant for consistency).
> 
> I think it's fine to have these in the Info file Local Variables section.

Ok, I'll do it.

-- 
Pat