Skip to content

Document steps and criteria for starting a new translation - #361

Open
jordikroon wants to merge 4 commits into
php:masterfrom
jordikroon:new-language-guide
Open

jordikroon wants to merge 4 commits into
php:masterfrom
jordikroon:new-language-guide

Conversation

@jordikroon

Copy link
Copy Markdown
Member

Every now and then interest for a new translation appears. With the main question to it how to make it an official translation hosted on php.net. This is becoming more relevant given it's now in reach to ask an LLM to translate doc-en during the morning and submit your work in the afternoon.

I am trying to set the criteria that they can work with. Disallowing them to go solo and enforcing them to team up before even attempting.

  • 3 translators to team up with
  • 3 months work during this period to show commitment
  • Define essential folders (though with 3 months of commitment, this should be easy-peasy).

Please share your thoughts.

Comment thread docs/joining.md Resolved
Comment thread docs/new-language.md Resolved
@Crell

Crell commented Nov 1, 2026

Copy link
Copy Markdown

I'm good with this, aside from the one nitpick above.

@prateekbhujel

Copy link
Copy Markdown

Hi, I’ve been working on a Nepali translation of the PHP Manual:

https://github.com/prateekbhujel/doc-ne

I’ve used AI to help with drafts, and I’m reviewing and correcting the language and technical content myself. Would the proposed restriction also apply to translations prepared this way? I’d like to understand what the team expects before continuing.

Thanks,
Pratik

Comment thread docs/joining.md
### 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,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about a "New Language" section in the existing translating file? This seems to be beneficial to me as it would spare introducing a new file for a subsection and may also help maintaining the documentation.

Comment thread docs/new-language.md
## 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. This issue is where

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From top of my head, the value LANG (of the modules) is a locale-name of the form:

LANG=language[_territory][.codeset]

where [.codeset] is obviously superfluous (phpdoc content is always UTF-8). (ref)

In my eyes it seems to be a good fit here, as reading about the changes reminded me about when I was starting and I found it very little documented; YMMV.

Comment thread docs/translating.md
@@ -3,12 +3,12 @@
**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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous pargraph just suggested editing. It's perhaps beneficial you move the new paragraph above it, especially as the content links back into the page here (mind also my earlier comment about the more integrated form).

@hakre

hakre commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Hi @prateekbhujel,

thank you for your work on the Nepali translation of the PHP Manual.

I’d like to understand what the team expects before continuing.

If I see it right, you just founded the Nepali translation team, congratulation!

Do you know about the PHP Community Discord server? If not, it might be interesting for you, there is also a dedicated channel about the PHP documentation. Maybe @tiffany-taylor can onboard you?

/edit

I’ve used AI to help with drafts, and I’m reviewing and correcting the language and technical content myself. Would the proposed restriction also apply to translations prepared this way?

Translation works fall under the same license as the original work AFAIK, which is very little as I'm not your lawyer. There is very little specific information within the PHP org on Microsofts Github in regard to the use of Large Language Models ("AI"), I tried to get more information from @jordikroon and @Crell in the past but no authoratative or procedural information was (made) available. I'd suggest to use a different venue to discuss this aspect of your contribution - e.g. Discord.

@hakre

hakre commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

Every now and then interest for a new translation appears. With the main question to it how to make it an official translation hosted on php.net. This is becoming more relevant given it's now in reach to ask an LLM to translate doc-en during the morning and submit your work in the afternoon.

Why then raising the barrier of entry @jordikroon? The trend to automation is since longer and the machine translations are getting better every three months if not faster. Especially if a translator trains their own systems you get the quality of a team of three much faster than in three months (if not even in three weeks).

@prateekbhujel

Copy link
Copy Markdown

Thank you so much @hakre! Really appreciate the warm welcome and encouragement.

I'll definitely jump onto Discord (https://phpc.chat) and connect with @tiffany-taylor and the docs team there. Thanks for pointing me in the right direction!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants