Translations in `entities.acronyms.ent` are not reflected in the rendered output
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 91
- Forks
- 59
- PR merge metrics
- No merged PRs in 30d
Description
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:662writes<!ENTITY LANG '$lang'> - Used:
doc-base/manual.xml:34reads 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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Trace how the language flows from doc-base/configure.php:662 into manual.xml and how render.php selects its language, then compare that with the php/infrastructure build-docs-lang-rsync template. Reproduce the pt_BR acronym output locally and verify that localized titles and language-specific feed IDs are generated consistently.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- build-system, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100