Hi Jordi,
Thank you for the thoughtful response. Your concern is completely reasonable, especially if the Persian documentation is eventually going to become a trusted source for a large audience.
Yes, AI/LLM tools have been used during the translation process, and I would like to be fully transparent about how they were used.
The project was not produced by sending the complete PHP Manual to a model and publishing the returned text. I built a multi-stage translation workflow around the PHP XML sources, including source inventory, translation-unit extraction, protected-content handling, Translation Memory, deterministic reconstruction, EN-Revision tracking, structural validation, residual-language checks, targeted human review, upstream synchronization, and full doc-base / PhD builds.
The recorded translation workflow used:
The workflow deliberately kept generated translations in REVIEW_REQUIRED state. Machine-generated entries were not globally marked as human-approved.
I also want to be very clear about the human-review status:
I cannot honestly claim that every sentence in all 10,973 translated XML files has already received an individual line-by-line human linguistic review.
What I have done is a combination of full-corpus deterministic validation and targeted human review of the highest-risk translation cases.
For example, the human linguistic review stage selected 574 mandatory high-risk rows:
All 252 repair cases were subsequently resolved. During the final release-candidate QA, an additional 73 hard residual semantic cases received manual semantic repair.
The final candidate also passed the structural and build gates, including:
-
10,973 translated Persian XML files
-
10,973 / 10,973 translated files with current/ready EN-Revision metadata
-
11,915 XHTML build outputs
-
13,133 PHP build outputs
-
0 UTF-8 failures
-
0 XML 1.0 failures
-
0 final structural failures
-
0 residual obvious-English findings
-
0 excess-Cyrillic findings
-
0 new duplicate xml:id issues introduced by the Persian candidate
-
0 hard-secret findings in the public staging repository
One correction to my original message is also important: the current public repository is not actually at 100% file-level translation coverage.
The final audited tree contains:
-
11,543 XML files
-
10,973 Persian translated XML files
-
185 do-not-translate files
-
385 additional files currently using English fallback
That corresponds to approximately 96.6% coverage of the translatable XML file set.
Regarding the single initial public commit: that was intentional and only represents the clean publication staging.
The internal development process contains many translation, repair, synchronization, QA, build, and release checkpoints. For the public repository I intentionally excluded internal Translation Memory storage, runtime state, temporary workspaces, backups, repair bundles, and internal project history.
So the initial commit is a validated publication snapshot, not evidence of a one-pass translation process.
I have attached a document named:
PHP-DOC-FA-VALIDATION-EVIDENCE.md
It summarizes the AI-assisted workflow, Translation Memory statistics, the exact scope of human review, QA results, build validation, upstream synchronization, publication staging, limitations, and an evidence index pointing to the underlying machine-generated project reports.
If useful, I can also provide the underlying JSON reports for any specific validation stage.
Most importantly, I agree with your point that automated QA cannot replace human verification of language and technical meaning.
I would therefore be very happy to treat the current repository as a candidate corpus and introduce a more explicit human-verification process before material is considered suitable for an official Persian translation.
For example, I can progressively verify sections/files in reviewable batches, record their human-verified status, use pull requests for that review history, and involve additional Persian-speaking PHP contributors.
I would appreciate your guidance on what level and form of human verification the PHP Documentation Team would consider appropriate before moving forward with official onboarding.
My goal is not to claim completeness prematurely, but to establish a process that the PHP Documentation Team can trust and that can be maintained over time.
Regards,
Soroush
···
From: Jordi Kroon jordikroon@me.com
Sent: Monday, September 21, 2026 15:18
To: Soroush Neyestani soroush.neyestani@live.com; phpdoc@lists.php.net phpdoc@lists.php.net
Subject: Re: Starting an official Persian (fa) translation of the PHP Manual
On 21 Sep 2026 at 07:04 -0400, Soroush Neyestani <soroush.neyestani@live.com>, wrote:
Hello PHP Documentation Team,
I would like to start and maintain a Persian (fa) translation of the PHP Manual.
I have prepared and publicly released a validated community release candidate here:
https://github.com/soroushneyestani/php-doc-fa
The current release contains:
10,973 translated XML files
11,543 XML files audited
96.6% coverage of translatable XML files
10,973 / 10,973 translated files with current EN-Revision metadata
11,915 XHTML build outputs
13,133 PHP build outputs
0 unresolved final structural QA errors
The translation is currently based on the following English documentation revision:
ebe570978c9a476a3c68abe53426b3c363f62eb5
The repository has been validated with the PHP documentation tooling, including doc-base and PhD.
I am currently presenting the project only as a community release candidate, not as an official PHP translation, because I would first like to coordinate the proper onboarding process with the PHP Documentation Team.
Could you please advise me on the next steps for officially adding Persian (fa), including the preferred repository/team setup, translation.xml, language registration, and any other requirements I should follow?
I would be happy to maintain the Persian translation and keep it synchronized with the English documentation.
Thank you,
Soroush Neyestani
GitHub: https://github.com/soroushneyestani
Repository: https://github.com/soroushneyestani/php-doc-fa
Hi Soroush,
First and foremost I would like to thank you for the interest in translating and maintaining the Persian translation.
I do have some questions regarding the current state.
Have you used AI/LLM tools to translate the documentation to its current state? If so, could you share your approach to this? My main concern right now, if I am very honest.
Currently everything is packed in 1 commit, many languages do not have 100% coverage and your translation seems to do. Which is impressive yet concerning. And it usually gets a few contributors together to get to that point.
As this translation should be the source of truth for a major target audience, we should at least have a guarantee that the contents have been verified by a real person.
Regards,
Jordi
(Attachment PHP-DOC-FA-VALIDATION-EVIDENCE.md is missing)