Re: [RFC] Separation of Third-Party Extension Documentation

On Friday 29 May 2026 10:18:59 (+02:00), Jordi Kroon wrote: > > I don't understand what the problem with translations. What is so special about > > english that it can be lift-and-shifted, but other languages cannot? What specific coordination is > > required from the translation team? > > Translations could be lift-and-shifted the same way English can. The asymmetry is about > responsibility after migration, not the migration itself.. > > A few concrete points: > > * Translations track the English version via revision hashes, so they > depend on the English source. English is canonical; while the other > languages are downstream of it. > * A majority of translations have less than 50% coverage > (https://doc.php.net/revcheck.php). > * The whole point of the RFC is to hand documentation responsibility > to the extension maintainers. That works for English because English > is the de facto language. It does not work for the other languages. > We can't reasonably assume an extension maintainer is fluent in > German, French, Japanese, etc. > * Structurally, carrying translations over would mean one contrib > repository per language, mirroring the current doc-en / doc-de / > doc-fr / doc-ja / etc. So the overhead the RFC is trying to >     reduce would be reproduced in the new location. > * It is already difficult to keep a single language in sync with > extension releases. Asking extension maintainers to keep N languages > in sync. Languages that the extension maintainer can't read or > understand. Thus a language the extension maintainer can't verify > the contents of. If we want to transfer responsibility, wouldn’t the only responsible course of action be to not only hand over the edit history in the canonical language, but also that of the translated works? Regarding what you say about the contrib repositories: They can be one repository per extension, so to be honest, I can’t really follow that line of reasoning. Which is perhaps why I feel that the ‘Shift’ in ‘Lift and Shift’ in the RFC leans too far to the right and appears misplaced to me. I’d prefer to see it further to the left, just like the ‘Shift’ in ‘Shift Left’: Assuming a new iteration is created, and once it passes CI, the build and source code are handed over (the ‘Shift’ operation in form of one repository), then deleting the translated books and their history is no longer required for the handover during ‘Lift’, as a single Git repository is already sufficient according to the discussion so far if I'm not mistaken. So my substantive question remains: is this a handover of responsibility under which we also want to act responsible? In that case, in my opinion, we should do us the favour and not make too many assumptions about what future editors will do with the work. Especially if that is done in the light of technical difficulties, as I'm confident we're able to handle it, so that we include the translation and the history in their current form. We should enable any future readers – rather than hindered – to act responsibly. The revision history is important – particularly when it comes to the documentation and its translation. We should lead them by the best example only, not telling them that is is a fruitless effort to organize their translations (or vice-versa, as you correctly wrote, only because English is canonical for the translation, after handing the books over, this can become entirely different.) -- hakre Translated from Englitsch to German back to Englisch with DeepL.com (free version)