php / php/phd

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

Open
#264 3 comments 0 reactions 0 assignees View on GitHub

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: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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.