From 965ad4662ce232ced55fbe0a922ec7760985cfdc Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Sat, 31 Oct 2026 19:06:54 +0100 Subject: [PATCH 1/4] Document steps and criteria for starting a new translation --- docs/new-language.md | 82 ++++++++++++++++++++++++++++++++++++++++++++ docs/toc.md | 1 + 2 files changed, 83 insertions(+) create mode 100644 docs/new-language.md diff --git a/docs/new-language.md b/docs/new-language.md new file mode 100644 index 0000000000..f8705fba7f --- /dev/null +++ b/docs/new-language.md @@ -0,0 +1,82 @@ +# Starting a new translation + +Thank you for wanting to translate the PHP Manual! This chapter explains how +to start a translation into a language that is not yet listed at +, and what is needed before it is published +on php.net. + +A translation is a long-term commitment. The manual has more than ten +thousand files and changes every day, so a translation is only useful as long +as people keep it up to date. That is why the steps below focus on finding a +team and building up steadily, rather than on translating as much as possible +at once. + +## 1. Check whether the language already exists + +Look for your language in +[`languages.php`](https://github.com/php/doc-base/blob/master/languages.php) +and in the [open issues](https://github.com/php/doc-base/issues) of doc-base. +If a repository or an issue for your language already exists, join that effort +instead of starting a new one. + +## 2. Open an issue and announce it + +Open an issue in [php/doc-base](https://github.com/php/doc-base/issues/new) +titled `New translation: {Language} ({LANG})`, where `{LANG}` is the +two-letter [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) +code. Introduce yourself and mention your GitHub username. This issue is where +others who want to help can find you, and where you post your progress. + +Then write to `phpdoc@lists.php.net` with a link to the issue, so the +documentation team and other translators see it. You need to +[subscribe to the list](https://news-web.php.net/php.doc) before you can post. + +## 3. Find a team + +You need **at least three translators** before a translation can be +published. Translating alone is a quick way to burn out, and a team can review +each other's work and keep going when someone has less time. Use the issue and +the mailing list to find others, and ask people in your local PHP community. + +## 4. Set up a repository + +Create a repository named `doc-{LANG}` under your own GitHub account. It +follows the structure of [php/doc-en](https://github.com/php/doc-en) (see +[Documentation structure](structure.md)), with a few rules: + +- Only add files that are translated. Missing files are taken from the English + manual automatically. +- Every translated file starts with an `EN-Revision` comment, explained in + [Translating documentation](translating.md). +- Add `language-defs.ent`, `language-snippets.ent` and a `translation.xml` that + lists the team, as in [doc-it](https://github.com/php/doc-it). + +Build the manual locally with your language to catch errors early, as +described in [Setting up a local build environment](local-setup.md). + +## 5. Translate the essentials first + +Start with these parts: + +- `language/` +- `reference/array/` and `reference/strings/` +- `chapters/`, `faq/`, `features/` and `install/` + +After that, continue with other commonly used extensions. + +## 6. Work together + +- Use pull requests, and let a team member review each one before it is merged. +- Prefer small, regular commits over large ones. +- Translation tools can help with a first draft, but a person must review + every file. Large machine-translated imports are not accepted: a wrong + translation is worse than a missing one, which falls back to the English text. + +## 7. Becoming an official translation + +When the essentials are translated and up to date, your team has at least +three active translators, and you have worked steadily for at least three +months, post an update in your issue and ask for the translation to be made +official. The documentation team will review it and, once agreed, move the +repository to the `php` organization, create a `doc-{LANG}@lists.php.net` +mailing list and publish the manual on php.net. diff --git a/docs/toc.md b/docs/toc.md index cf35443a7c..4e540451e0 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -8,6 +8,7 @@ - [Style guidelines](style.md) - [Coding standard for examples](cs-for-examples.md) - [Translating documentation](translating.md) +- [Starting a new translation](new-language.md) - [Joining the team](joining.md) ## Appendices From d2c3c5b9bb5a18c8aae7af7b081d96026381d77a Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Sat, 31 Oct 2026 19:09:30 +0100 Subject: [PATCH 2/4] improve guidance for new language translations --- docs/joining.md | 4 ++++ docs/translating.md | 3 +++ 2 files changed, 7 insertions(+) diff --git a/docs/joining.md b/docs/joining.md index a552ff39f1..93df6f8248 100644 --- a/docs/joining.md +++ b/docs/joining.md @@ -25,6 +25,10 @@ version which allows you to send a message but doesn't send you any emails ### For translators You should send your message to the appropriate `doc-{LANG}@lists.php.net` mailing list. +If there is no `doc-{LANG}` list because your language has no translation yet, +write to `phpdoc@lists.php.net` instead and read +[Starting a new translation](new-language.md). + ## Informal discussion The mailing lists above are the primary communication forum. In particular, decisions and plans should be made on the list so they are recorded in the diff --git a/docs/translating.md b/docs/translating.md index 64e58ceca4..744823ddb4 100644 --- a/docs/translating.md +++ b/docs/translating.md @@ -3,6 +3,9 @@ **Watch out:** this chapter describes special parts of the whole editing process. You will also have to follow other steps from the [editing manual sources](editing.md) section. +If your language does not have a translation yet, read +[Starting a new translation](new-language.md) first. + Translating documentation into other languages might look like a complicated process, but in fact, it's rather simple. From a91015f162cfbaca7d51328f0d845cd33a542629 Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Sat, 31 Oct 2026 21:18:20 +0100 Subject: [PATCH 3/4] Add a more bold statement regarding LLM usage --- docs/joining.md | 3 +-- docs/new-language.md | 11 ++++++++--- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/joining.md b/docs/joining.md index 93df6f8248..9a47824d7d 100644 --- a/docs/joining.md +++ b/docs/joining.md @@ -26,8 +26,7 @@ version which allows you to send a message but doesn't send you any emails You should send your message to the appropriate `doc-{LANG}@lists.php.net` mailing list. If there is no `doc-{LANG}` list because your language has no translation yet, -write to `phpdoc@lists.php.net` instead and read -[Starting a new translation](new-language.md). +read [Starting a new translation](new-language.md). ## Informal discussion The mailing lists above are the primary communication forum. In particular, diff --git a/docs/new-language.md b/docs/new-language.md index f8705fba7f..2b324d6491 100644 --- a/docs/new-language.md +++ b/docs/new-language.md @@ -68,9 +68,14 @@ After that, continue with other commonly used extensions. - Use pull requests, and let a team member review each one before it is merged. - Prefer small, regular commits over large ones. -- Translation tools can help with a first draft, but a person must review - every file. Large machine-translated imports are not accepted: a wrong - translation is worse than a missing one, which falls back to the English text. + +### No LLM translations + +Do not submit translations made with an LLM or another machine translation +tool. Readers can already do this themselves in their browser, so it adds +nothing to the manual. Fixing generated text also takes more effort than +translating from scratch, and its mistakes are easy to miss. Such +translations will not be accepted. ## 7. Becoming an official translation From 4f36200b80c3edd85ddc04841285a62c15467202 Mon Sep 17 00:00:00 2001 From: Jordi Kroon Date: Sun, 1 Nov 2026 18:57:12 +0100 Subject: [PATCH 4/4] Remove introduction line --- docs/new-language.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/new-language.md b/docs/new-language.md index 2b324d6491..6c075f6342 100644 --- a/docs/new-language.md +++ b/docs/new-language.md @@ -21,10 +21,8 @@ instead of starting a new one. ## 2. Open an issue and announce it -Open an issue in [php/doc-base](https://github.com/php/doc-base/issues/new) -titled `New translation: {Language} ({LANG})`, where `{LANG}` is the -two-letter [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) -code. Introduce yourself and mention your GitHub username. This issue is where +Open an issue in [php/doc-base](https://github.com/php/doc-base/issues/new) titled `New translation: {Language} ({LANG})`, +where `{LANG}` is the two-letter [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code. This issue is where others who want to help can find you, and where you post your progress. Then write to `phpdoc@lists.php.net` with a link to the issue, so the