Translations in `entities.acronyms.ent` are not reflected in the rendered output

[KentarouTakeda]

Summary

Translating acronym expansions has no effect on the rendered localized manual. Here is what I see for CLI in pt_BR.

Translation: https://github.com/php/doc-pt_br/blob/d4429c51d33261cd7be1d6622e44da7212e7ba05/entities/entities.acronyms.ent#L95

Interface/Interpretador de Linha de Comando

Rendered output: https://www.php.net/manual/pt_BR/features.commandline.php

<abbr title="Command Line Interpreter/Interface">CLI</abbr>

Cause and options

Option 1: fix in the build

render.php reads <language>/entities/entities.acronyms.ent directly. #262 added support for other languages, but when nothing is specified, render.php takes the language to be the default en.

Passing --lang pt_BR in my local build produced the correct output:

-<abbr title="Command Line Interpreter/Interface">CLI</abbr>
+<abbr title="Interface/Interpretador de Linha de Comando">CLI</abbr>

So if the goal is only to fix the published manual, I think adding the language option to the build is the smallest change:
https://github.com/php/infrastructure/blob/61b6f2989bbfeae5dab7c7b293e954e6858a46f0/roles/properties/rsync/templates/build-docs-lang-rsync#L10-L16

Option 2: fix in render.php

Letting render.php pick up the language that configure.php was given may be the more fundamental fix. In most of the CI/CD setups and documentation across php/infrastructure, php/doc-base, php/phd and php/doc-*, render.php is called without a language. If it were the default, nobody would have to pass the option.

(I ran into this while translating entities.acronyms.ent, when I could not see the result in my local build.)

PhD is a bit complex for me, but the pieces to carry this setting through seem to already exist:

• Produced: doc-base/configure.php:662 writes <!ENTITY LANG '$lang'>
• Used: doc-base/manual.xml:34 reads it in <set ... xml:lang="&LANG;">

I see no reason to give configure and render different languages, so making them agree when nothing is specified seems reasonable to me.

A small trade-off

Either way, the document IDs served in the Atom feeds contain the language, so the ID of every entry already published would change. For example, the ja feed:

https://www.php.net/manual/ja/feeds/features.commandline.atom

<id>tag:php.net,2009-10-13:/manual/en/file/features.commandline</id>

The ja document identifies itself as en. If anyone is subscribed to these, they would see every entry as new one time.

That feed URL is not linked from anywhere in the current manual, so I doubt many people are subscribed. The IDs also collide across all languages today, so I think having each feed identify its own language is worth the one-time churn.

[alfsb]

After php/doc-base#336 lands, there will be more options.

Like Option 2, read the "language dir" used for manual build directly from doc-base/temp/lang.

And more one option:

Option 3: read merged entities from doc-base/temp/doctype.dtd

This option has the disadvantage that it is still uses DTD entity format, but has the advantage that it contain all entities collected by doc-base/configure.php, be ir a unique language dir, or be ir two language dirs (translation and fallback), and also that it has a fixed path, relative to the manual.xml being rendered.

So, for example, a language has translated only half of entities.acronyms.ent, then doc-base/temp/doctype.dtd will contain all acronyms defined, both translated ones and fallback ones.

[KentarouTakeda]

Thanks, that's helpful. Option 3 looks right to me. It would let a language translate only part of the file, and it leaves $config->language alone, so the feed IDs I mentioned wouldn't move.

[alfsb]

There is another advantage in Option 3. Entities collected into doc-base/temp/doctype.dtd will be in correct order. For the longest time, manuals contained almost all entities duplicated, bloating the manual loading, and relied on SGML/DTD semantics (first wins) for selecting one of each duplicated entity.

The new file-entities.php and text-entities.php remove almost all duplications, but there will be a long time before language-snippets.ent is completely converted, in all languages, so duplications will continue to exist in all translations.

So it is not only a matter of reaching some entity somewhere, but also of selecting the correct one, from a "sea" of files and duplications. Using doctype.dtd as "source of truth" will resolve all that.