Re: Musings on our translated documentation build

[Jonas Hahnfeld]

On Wed, 2023-01-04 at 22:58 +0100, Federico Bruni wrote:
> Il giorno mer 4 gen 2023 alle 14:39:47 +0100, Jonas Hahnfeld 
> <hahnjo@hahnjo.de> ha scritto:
> > The other two formats we care about for the translated documentation
> > are PDF and HTML. Of the two, HTML is arguably the more complex one in
> > terms of infrastructure for cross-references: For PDF, we just link to
> > the (translated) heading in the right PDF file, and that's it. For the
> > split HTML build, however, we want the @node's to end up in a .html
> > file based on their English equivalent so that automatic language 
> > works if you open a page without the .html extension (question 0: do we
> > want to keep this ability?).
> 
> It's a good question. Some find it annoying, e.g. if you have a 
> localised browser but you want to read the english pages (because 
> translation is out-of-date or for other reasons). There is a 
> workaround: setting english as preferred language, but this affects any 
> website you visit.

Yes, that's me basically. I could probably solve my personal use case
by proposing a patch that keeps the .html extension in links inside the
English documentation (so whenever you chose English, you stay with the
untranslated version), but I'm pretty sure others want a different
behavior (for example you below, I think). Anyway, I will take this as
"we probably want some automatic switching in one way or another",
which requires identical .html file names to start with.

> I would prefer if setting a language was an explicit choice of the user.
> So an italian page should link to the italian pages, if available, 
> otherwise fall back to english.

This is the current behavior, no? Apart from the fact that the language
choice is currently coming from the browser...

> See also:
> https://gitlab.com/lilypond/lilypond/-/issues/2273
> 
> > On the other hand, we obviously want the link
> > text to be translated, which is why we have translated @node's and
> > @section's but the English version in the @translationof annotations.
> > Based on the latter, we generate .xref-map files to have a mapping for
> > cross references and then adjust file names and links to them in our
> > texi2html customization file.
> > 
> > Now, this works in our current setup, but it seems to me that there is
> > an easier way to achieve this with "native" Texinfo tools: Instead of
> > 
> > @node Translated
> > @section Translated
> > @translationof Original
> > 
> > we could also write
> > 
> > @node Original
> > @section Translated
> > 
> > which would take care of the .html file names automatically (modulo 
> > the lower-casing which we do for aesthetics, but that's easy and
> > potentially even more debatable).
> > 
> 
> It sounds interesting...
> 
> 
> > The obvious downside is that references in the translated 
> > documentation get a bit more complex:
> >  * For references in the same document (say inside the NR), we'd have
> > to write @ref{Original} instead of @ref{Translated}. Together with
> > @xrefautomaticsectiontitle on, this will still show the translated
> > section title for PDF and HTML (does not seem to work for .info, but
> > see first paragraph why this isn't actually a problem), even if it
> > looks a bit weird / funny.
> >  * For cross-references, we'd have to manually provide the mapping. So
> > instead of @ruser{Translated}, we'd have to write
> > @rusernamed{Original,Translated} to make the link text appear
> > translated.
> > 
> 
> It would be better IMO, because a translator would not have to update 
> all the @ref after translating a page.

Interesting. I guess this is another aspect of what I described as
"self-contained"...

> IIRC updating/translating the @ref is not necessary for HTML documents,
> but it is for PDF documents. What you write below is probably the
> explanation of this difference.

Our texi2html customization has a lot of fallback code, so I guess it
transparently handles untranslated cross-references correctly?

> > For historical context: It appears that in the distant past, 
> > translated documentation was written with
> > 
> > @node Original
> > @section Original
> > 
> > which obviously works for the .html file names. To still get 
> > translated link text, there were two scripts: html-gettext.py replaced
> > the text in the already generated .html files, and texi-gettext.py did
> > the same before calling texi2pdf. Compared to that state, using "@section
> > Translated" automatically takes care of references in the same 
> > document (only requiring us to specify the @node in English). Looking at
> > the French documentation, that's the largest fraction with around 1400
> > occurrences while there are "only" 94 matches of plain @ruser
> > (@rusernamed doesn't count here because the removal of .xref-map would
> > just change the first argument from the translated version to the
> > English @node, while the actual display text stays exactly the same).
> > 
> > What do people think, especially translators? Would this "annoyance" 
> > be acceptable if it provides a significant simplification of our
> > infrastructure? Another advantage would be that each document is self-
> > contained, ie no more recompilation of all documentation for changes
> > that do not affect cross-references at all.
> 
> What is the "annoyance" exactly?

1. All @ref{Translated} become @ref{Origin}, but as far as I understand
that may actually be an advantage.
2. All @ruser{Translated} become @rusernamed{Origin,Translated}, ie you
have to provide both the original @node *and* the translated display
text. For @unnumberedsec, we may even need a third argument to get the
anchor correct - not sure how often that is actually needed.

> I would like to see a test for a language in order to better understand.
> Would you take care of all the changes required in translated files? 
> ("swapping" @translationof and @section, changing the @ref occurrences, 
> ...)

Yes, this would be automated, I hope. It's actually funny that the
script for the last change in 2008 / 2009, from the state that I
describe in the "historical context" above to what we have today, is
still in the repository: scripts/auxiliar/tely-gettext.py

signature.asc
Description: This is a digitally signed message part