PHP-DOC-FA: Building a Maintainable Persian Translation of the PHP Manual

Overview

PHP-DOC-FA is a public, community-maintained release candidate of the Persian (fa) translation of the PHP Manual.

The project was created with a goal that goes beyond translating individual pages. The intention is to build a translation repository that is technically structured, auditable, buildable, maintainable, and suitable for long-term collaboration.

The current public repository is available at:

https://github.com/soroushneyestani/php-doc-fa

At the time of this release, the repository is not being presented as an official PHP translation repository. The public release has been prepared and validated independently, while official onboarding with the PHP Documentation Team is still pending. This distinction is important: the repository is public and technically validated, but its official integration into the PHP documentation infrastructure has not yet been completed.

Why this project exists

PHP has one of the largest and most important technical documentation ecosystems in web development. For many developers, the PHP Manual is not simply a reference website; it is part of the everyday development workflow.

However, language can still be a barrier.

A high-quality Persian documentation layer can make the PHP Manual easier to use for:

• developers who are more comfortable reading technical explanations in Persian,
• students who are learning PHP for the first time,
• developers who understand English but prefer Persian explanations for difficult concepts,
• technical instructors and educational institutions,
• translators and documentation contributors,
• and the broader Persian-speaking open-source community.

The purpose of PHP-DOC-FA is therefore not merely to “translate PHP into Persian.” The objective is to create a maintainable documentation project with enough technical discipline that contributors can understand what has been translated, which English revision each translation corresponds to, what remains untranslated, whether the repository builds successfully, and how future updates can be integrated.

Current project scale

The current release contains a substantial amount of translated and validated material.

Key numbers

• 10,973 translated XML files
• 11,543 XML files audited
• 96.6% coverage of translatable XML files
• 113,799 Translation Memory entries
• 74,692 unique safe Translation Memory source units
• 455,272 Translation Memory event records
• 11,915 XHTML build outputs
• 13,133 PHP build outputs
• 10,973 / 10,973 translated files with current EN-Revision metadata
• 0 unresolved final structural QA errors
• 0 new duplicate xml:id issues introduced by the Persian translation
• 0 final Cyrillic contamination findings
• 0 obvious residual-English findings in the final QA gate
• 0 hard-secret findings in the public staging repository

These figures are not intended as marketing estimates. They come from the validation and release-preparation process used for the public repository.

Translation coverage

The English documentation baseline used for the release contains 11,543 XML files with corresponding documentation paths.

Of those:

• 10,973 are present as translated Persian XML files,
• 185 are identified as do-not-translate material,
• 385 additional files are currently not included as Persian translations and are expected to use the English fallback model.

When do-not-translate files are removed from the denominator, the Persian repository covers approximately 96.6% of the translatable XML file set.

This is a file-level coverage metric. It should not be interpreted as a claim that every sentence has been manually reviewed by a human translator or that every technical wording choice is final. Translation quality can continue to improve through review, issue reporting, terminology refinement, and community contributions.

A sparse translation repository by design

The public repository is intentionally sparse.

Instead of copying every English source file into the Persian repository, the public translation tree contains the translated Persian documentation files and a small number of required support files.

This model keeps the repository focused on translation-specific content and makes it possible to distinguish clearly between:

1. content that has a Persian translation,
2. content that is intentionally not translated,
3. and content that still falls back to English.

At initial publication, the validated translation payload contained:

• 10,973 translated XML files
• 5 support files
• 10,978 tracked files in the initial public staging commit

A separate README commit was then added, bringing the public repository to 10,979 tracked files.

Keeping the initial translation payload and the repository presentation layer in separate commits also provides a clean historical checkpoint for the release candidate.

English revision tracking

One of the most important challenges in documentation translation is synchronization with the upstream English source.

A translated page can be linguistically good and still be technically outdated if the English documentation has changed.

For that reason, the release candidate includes EN-Revision metadata for every translated XML file.

Current result:

10,973 / 10,973 translated XML files have current EN-Revision metadata and are marked ready in the validated release candidate.

The English documentation baseline used for this release is tied to the following upstream revision:

ebe570978c9a476a3c68abe53426b3c363f62eb5

The public translation staging commit was:

018b87e9ba2a9ae50dcd5cc4217ed0c305ca9427

The subsequent README commit is:

ca3c2b25da9fb7c06ecc586616b11f67905e04e4

This separation helps preserve a verifiable release history.

Translation Memory

A large translation project becomes much easier to maintain when repeated source material can be tracked and reused consistently.

PHP-DOC-FA therefore uses a Translation Memory dataset as part of the translation and reconciliation workflow.

The validated Translation Memory statistics for the current release are:

• 113,799 entries
• 74,692 unique safe source units
• 455,272 event records
• 0 unresolved Translation Memory conflicts in the validated reconciliation state

The Translation Memory is not published as part of the public PHP documentation repository. It belongs to the internal project tooling and workflow rather than the final documentation payload.

This separation is intentional. The public repository contains the documentation needed for the translation project, while internal runtime data, project state, checkpoints, and tooling history are kept outside the public translation tree.

Validation and quality assurance

The public release candidate went through multiple QA stages before publication.

The final validation state included checks for:

• UTF-8 integrity,
• XML 1.0 validity,
• document structure,
• translation-specific residual English,
• unexpected Cyrillic text,
• duplicate xml:id behavior,
• Git whitespace correctness on the canonical release candidate,
• build-system compatibility,
• documentation-tooling integration,
• public staging privacy checks,
• and secret-like data detection.

Final QA highlights

• UTF-8 / XML / structural validation: PASS
• Residual obvious English: 0
• Final Cyrillic contamination findings: 0
• New duplicate xml:id issues: 0
• Hard secret findings: 0
• Public staging local-path findings: 0
• Canonical release-candidate git diff --check: PASS

During the publication QA, two strings resembling private-key headers were detected. They were reviewed and identified as documentation examples inherited from the English PHP documentation, not real credentials or project secrets.

Build validation

A documentation translation is much more useful when it can actually pass the documentation build pipeline.

The release candidate was therefore tested using the PHP documentation tooling, including doc-base and PhD.

The validated outputs were:

• 11,915 XHTML build files
• 13,133 PHP build files

The important point is not simply the output count. The build process demonstrates that the repository is structurally usable by the documentation toolchain rather than being only a collection of translated text files.

The final release candidate successfully passed the relevant build checks used during the project’s validation process.

Public repository and release history

The project is publicly available at:

https://github.com/soroushneyestani/php-doc-fa

The initial public repository was created as a fresh, one-commit staging history rather than publishing the internal development history.

This was deliberate.

The public repository does not contain:

• internal project checkpoints,
• runtime state files,
• Translation Memory storage,
• internal backups,
• private tooling history,
• temporary repair bundles,
• or the full internal Git history used during development.

The first public commit represents the validated documentation staging tree.

A second commit adds the project README.

This gives the public repository a cleaner and more understandable history while keeping the internal engineering workflow private.

Community Release Candidate status

The project currently uses the term Community Release Candidate.

This wording is intentional.

The repository is public. The translation tree has been validated. The project can be reviewed and contributed to. However, official onboarding of Persian (fa) into the PHP Documentation Team’s translation infrastructure is still pending.

Until that process is completed, the project should not be described as:

• “the official Persian PHP Manual,”
• “officially accepted by PHP,”
• or “the official PHP Persian translation.”

A more accurate description is:

A public, validated, community-maintained Persian translation release candidate of the PHP Manual, pending official PHP Documentation Team onboarding.

If official onboarding is completed in the future, the project status and public wording can be updated accordingly.

What can still improve

A successful build does not mean the translation is finished forever.

Technical documentation evolves continuously.

Future work may include:

• terminology refinement,
• human review of difficult technical passages,
• synchronization with newer English revisions,
• style consistency improvements,
• correction of typographical issues,
• review of code-related explanations,
• review of extension-specific terminology,
• improved Persian technical vocabulary consistency,
• accessibility improvements,
• and community-driven issue resolution.

The current release should therefore be seen as a strong technical baseline rather than the final immutable form of the Persian PHP Manual.

Contributions

Contributions are welcome.

Useful contributions may include:

• reporting mistranslations,
• correcting Persian wording,
• improving technical terminology,
• fixing punctuation or typography,
• identifying outdated translations,
• synchronizing a file with a newer English revision,
• reviewing code-related explanations,
• reporting XML issues,
• and proposing documentation workflow improvements.

When a translated XML file is changed because the corresponding English source changed, its revision metadata should also remain synchronized with the English source revision.

The project is intended to remain auditable and maintainable, so technical correctness and source synchronization are as important as natural Persian wording.

Why the numbers matter

Large technical translation projects are often described with vague terms such as “complete,” “almost finished,” or “fully translated.”

PHP-DOC-FA tries to avoid that style of reporting.

Instead, the project exposes concrete engineering metrics:

10,973 translated files shows the size of the Persian document set.

11,543 audited XML files shows the scale of the documentation tree that was evaluated.

96.6% translatable-file coverage gives a defined coverage metric rather than a subjective completeness claim.

113,799 Translation Memory entries shows the amount of translation data processed and reconciled.

11,915 XHTML outputs and 13,133 PHP outputs demonstrate that the project has been exercised through the documentation build tooling.

0 unresolved final structural QA errors records the final structural QA state of the validated release candidate.

None of these numbers means that community review is no longer necessary. They mean that the public release has a measurable technical baseline.

Open source and long-term maintainability

The project is public because technical documentation becomes more useful when it can be inspected, challenged, corrected, and improved.

Publishing the repository makes it possible for other developers to:

• inspect individual translations,
• compare them with English source material,
• open issues,
• propose corrections,
• review terminology,
• and contribute future updates.

The long-term goal is not simply to keep a static Persian snapshot online.

The more meaningful goal is to establish a maintainable translation workflow where English revisions can be tracked, Persian files can be updated systematically, and contributors can understand the state of the documentation without relying on hidden manual processes.

For Persian-speaking developers

For Persian-speaking PHP developers, the project is intended to provide a lower-friction path into the official concepts and structure of the PHP Manual.

Technical English remains important, especially for professional software development. A Persian translation is not intended to replace English-language learning.

Instead, it can serve as an additional layer:

• a learning aid,
• a clarification tool,
• a bridge for complex topics,
• a teaching resource,
• and a way to broaden access to high-quality technical documentation.

For experienced developers, the Persian version may also make it easier to teach, review, or explain PHP concepts to Persian-speaking teams and students.

For contributors and reviewers

The project is particularly interested in contributions from people with experience in:

• PHP development,
• technical writing,
• software localization,
• Persian language editing,
• XML / DocBook,
• documentation engineering,
• and open-source project maintenance.

A technically correct translation still benefits from language review.

A linguistically elegant translation still benefits from developer review.

A maintainable documentation project needs both.

Project repository

GitHub:
https://github.com/soroushneyestani/php-doc-fa

The repository currently contains the public Persian documentation release candidate and its project README.

Issues and pull requests can be used to discuss corrections and improvements.

Maintainer

Soroush Neyestani

GitHub:
https://github.com/soroushneyestani

Final note

PHP-DOC-FA is the result of treating documentation translation as an engineering problem as well as a language problem.

Translation quality matters.

But so do revision tracking, repository structure, validation, reproducibility, build compatibility, privacy checks, and a clean contribution model.

The current public release establishes that baseline:

10,973 translated XML files.
96.6% coverage of the translatable XML tree.
113,799 Translation Memory entries.
11,915 XHTML build outputs.
13,133 PHP build outputs.
0 unresolved final structural QA errors.

The repository is now public, reviewable, and open for improvement.

Official PHP Documentation Team onboarding remains pending, and the project will continue to use accurate community-release wording until that process is completed.