Repository navigation
Translations in entities.acronyms.ent are not reflected in the rendered output #264
Description
Activity
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.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->languagealone, so the feed IDs I mentioned wouldn't move.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.
doc-base/configure.phpnow outputs adoc-base/temp/doctype.dtdat each build, complete with all DTD entities used by manual assembling, in DTD order (first wins).There are still duplications (language-snippets.ent and struggling/abandoned translations that have not moved from other DTD entity files), but now fully translaed manuals, down to
entities.acronyms.ent, are now possible.Reacted by KentarouTakeda
Summary
Translating acronym expansions has no effect on the rendered localized manual. Here is what I see for
CLIin pt_BR.Translation: https://github.com/php/doc-pt_br/blob/d4429c51d33261cd7be1d6622e44da7212e7ba05/entities/entities.acronyms.ent#L95
Rendered output: https://www.php.net/manual/pt_BR/features.commandline.php
Cause and options
Option 1: fix in the build
render.phpreads<language>/entities/entities.acronyms.entdirectly. #262 added support for other languages, but when nothing is specified,render.phptakes the language to be the defaulten.Passing
--lang pt_BRin my local build produced the correct output: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.phpLetting
render.phppick up the language thatconfigure.phpwas 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.phpis 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:
doc-base/configure.php:662writes<!ENTITY LANG '$lang'>doc-base/manual.xml:34reads it in<set ... xml:lang="&LANG;">I see no reason to give
configureandrenderdifferent 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
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.