And again about translating PHP documentation

Background

When two years ago I needed to read the description of one of the functions, I opened Google, drove the name of this function and clicked on the link to the Russian description on the php.net website. It immediately struck me that the description was incorrect - the third parameter, added in far from recent PHP releases, was corny. With a shrug, I switched to the English version, where everything was correct and consistent with the current state of things.

However, the splinter remained in my memory and, after a while, I decided to study the issue and find out exactly how the documentation is localized. Literally the third line of the search results led to a rather ancient article on the hub , after reading which there was a desire to join the project.

Actually, there will be a rather chaotic story about how things are now with Russian localization, what problems had to be faced and what conclusions can be drawn from all this.

For starters, about how things are now.

The project involved one and a half digger in the mode of updating the modified pages and proofreading. Something new is translated extremely rarely due to the banal lack of time and ... tiredness probably.

Currently translated 7.147 files out of 12.992. In terms of quantity it is 55%, but in volume it is 67.6%. Steeper than Russian localization, only the Japanese (63%), Spaniards (65.5%) and French (77.3%).



But more importantly, 100% of the translated pages are relevant.

What happened two years ago.

The situation is best described by the answer to my question on the mailing group of one of the main Irker maintainers :

At the moment, the translation into Russian is in some suspended animation.
All active translators have lost interest or cannot find the time for it
(alas, including me). And all the new people who showed interest also somehow
quickly disappear =)

In fact, the state of localization looked something like this.



Sorry, I didn’t think of taking screenshots at that moment.

On this, perhaps, with the progress report, I will end and go on to talk about the problems.

What had to face

The rescue of drowning people is the work of the drowning people themselves.

The first and probably one of the biggest problems is team communication.
Having translated the first hundred pages and created the patch, I realized that I had no idea what to do next. When a patch has been waiting for about two weeks without any feedback, the desire to continue to do something disappears completely. Actually, at that moment I was saved by the fact that 100 pages was not 5 pages and it was commonplace to throw away the work done. Therefore, it was decided to knock on all doors, maybe someone will respond.

Later, I already learned that the easiest way is to write to a mailing group (a completely monstrous way to communicate in 2016+), but at that time I had to play a detective story and look for their mailing addresses and send letters using translators' nicknames. Of all the letters sent, the answer came only from Irker , and, for the good, just from that moment, wrap everything up ...

Running with obstacles behind the departed engine.

Before starting to translate new pages, it was logical to put in order outdated for a start. For the price of documentation is worthless if one third of it does not correspond to reality. About 700 pages were waiting to be put in order. Plus, the process of updating the English branch to match PHP 7 was just going on, so their number was coming and coming.

It was about a steam locomotive, and now about obstacles.

The worst part was that half of these pages were already being tried by someone. Often, this was not done to the end, either rather crookedly, or after updating, the main page changed several times. In general, he is still an adok.

And let's fix the indentation in all documents with a script?

A couple of times there was a situation when in the English branch a script ruled something immediately on all documents. Usually, instructions on automatic updating for translators were laid out next to them, but in fact anyway then I had to reconcile 100-200 pages manually. Sad but true.

I clicked something and it all broke.

One of the most unpleasant events is to receive a letter in the mailing list:

The ru build of the PHP Manual is broken, so it does not validate or build. Please fix it! ;)
Attached is the full log
Love, The docs.php.net server
...
Eyh man. No worries. Happ shittens. Try again after fixing the errors above.
==============> Something happenend when snapshotting en
Failed completely
=============> Please have a look!

If the evening build broke after the morning commit of one file, then, for the most part, everything is simple - you go and verify. But if there were about twenty commits, and the number of files is measured in a couple of hundred, it’s easier to hang yourself, because both the attached log and the diagnostic mode do not always add an understanding of where the problem is. And the problem can easily be on the side of the main English branch, and then the carcasses are generally light.

And wiped his creation from the face of the earth - Easy, easy, with inspiration. ©

Vandals. Yes. Fortunately, not as much as it could be, but you have to periodically clean out the stables from everything else, starting from the simple "x * x x * x X * y was Vasya here" and ending with spoofed links to phishing sites.

Have you learned Finnish?

Terms are still a headache. For many English-speaking terms, there are no banal analogues in the Russian language. And if it comes to describing a narrowly specialized extension, for which, in principle, there is no adequate description even in English, then it becomes very sad. Sometimes it takes several times longer to translate one small page than a dozen voluminous sheets of text about widely used things. On the other hand, you will learn a lot.

conclusions

1. You can use Russian PHP documentation. It is 100% relevant and will remain so in the foreseeable future.
2. If, suddenly, after this publication, those who want to help run away, then you can even expect an increase in the translated articles.

References

Online Editor
Instructions for using the online editor for the authorship of Irker P.S. Distribution
Group

: If interested, I can generally talk about how the process of writing PHP documentation works, what is good and what is not good in it.

At the request of one and a half excavators, lex111 , I'm half there :)

Not so long ago, I created a Git repository on GitHubdocumentation (I remind you that it uses svn, for those interested there is a checklist for migrating to git), where everyone can subscribe to updates (Watch button), then notifications of new commits in the documentation will be shown in your feed, or marked with an asterisk (Star button) if you like the current quality of the documentation :). So, join the improvement and further development of the documentation, you will learn a lot of new and useful!

UPD Created a channel in slack . Who cares to talk - come in.