Tool: edit.php.net

This year, Yannick Torrès (yannick) created a handy web-based tool for translating PHP documentation. edit.php.net allows everyone to easily and quickly translate any page.
This article is a technical continuation of the article "A team of translators of PHP documentation needs help ."
UPD : The site may lag because of habraeffekta.

---

On each manual page there is a link to edit it at edit.php.net.

Clicking on it we will get to the authentication page, where we immediately select the Russian language for translation without hesitation.

Then we advise you to immediately log in with your google or facebook account, this will allow you to work on the transfer under the same login from different computers. (Otherwise, create a temporary account Anonymous #xxxx). To do this, on the right, first confirm your account in google or facebook, and then press Use this credentials and Anonymous Login.

Here is the home screen of the site with all sorts of, if not much, but useful widgets. On the left - the side menu, which in the process can be hidden, so as not to interfere. Most menu items are intuitive. We will describe to you an approximate cycle of transferring files to edit.php.net:

1) Choose what to translate: Untranslated files or non-updated files. Or you can select the files to be scanned from the “files to be read” section.
2) As soon as you start translating a file, it moves to “files in progress” and is assigned to you. If you are editing a non-updated file, you will also see its English version and changes in it compared to the old version.

At the beginning of each file with a complete translation, three special tags are needed.

<!-- EN-Revision: 301114 Maintainer: someone Status: ready --> <!-- Reviewed: no --> <!-- $Revision: 311957 $ --> 

')
The first tag indicates the revision of the original English file at the time of translation, the status of the translation, as well as the nickname of the person who will accompany the translation of this file in the future (this is unfortunately not your nickname, but the SVN account of the responsible ru-doc member).
Example: in the English file there is a <! - $ Revision: 111111 $ -> tag, in the Russian file you add the <! - EN-Revision: 111111 Maintainer: someone Status: ready -> tag.

The second tag indicates that this file will not prevent additional reading - it is always useful to look at the translation for several people. If you checked the “file for proofreading”, you can put the value Reviewed: yes on this tag. (i.e., <! - Reviewed: no -> if no one has rechecked the translation, and <! - Reviewed: yes -> if it was rechecked)

The last tag is technical, it will contain the revision of the translated file.
Those. it is enough that it is simply, for example, without a number <! - $ Revision: $ ->.

3) When the translation or verification of the file is completed - in the context menu of the file, you can create a “patch” for verification. UPD : The patch must be done necessarily - it is he who signals to us that you have finished transferring files!


As you can see - three simple points. What will happen to these files next? Of course, we are all adults and we understand that everyone should not be given the opportunity to upload anything to the server. Therefore, all your patches will be checked by us. The most active translators will join our ranks and help us more quickly consider patches. We also undertake to indicate your nickname as the author or participant of the file transfer for each commit of patches - each person’s work is valuable and there’s no point in keeping silent about it.

Tips:
- Save more often, anything can happen and it will be a pity to lose your work.
- Group files into patches by meaning. For example, if you transferred several documentation files to an extension, it makes sense to add them to a single patch with the name of this extension.

I ask you in advance to take into account that so far we are few and we are engaged in translation in our own time. If there is an influx of volunteers, then there may be delays in checking your patches.

Alternative

Initially there was no edit.php.net, but a svn repository. Rather not, but there is. In fact, edit.php.net also works with this repository. It’s much more convenient to work directly with SVN and use the docbook tool.

So, the online editor is inconvenient for you, you have your own cool editor or IDE, in which your performance just rolls over. Well, or simply the Internet is not always available, in any case, consider the option of local work through svn.

You will need any XML editor, svn client, and php from the command line (also known as php cli).

I will describe the installation for Ubuntu 11.04, for the other platforms, adjust accordingly.

So, for working with documentation it is convenient to use the so-called sparsed repository, which combines 3 repositories at once:

• doc-base (system scripts to build translation)
• en (the original version of the documentation in English)
• ru (translation of documentation in Russian)

 $ svn co https://svn.php.net/repository/phpdoc/modules/doc-ru/ phpdoc-ru 

This command will upload all the files we need to the phpdoc-ru folder (by the way, it’s convenient to browse the web through a similar link, svn.php.net/viewvc/phpdoc/modules/doc- in which the repository is replaced with viewvc).

Upon completion of the upload, you can already work with the received files. The scheme of work is the same as in the online editor:

1) Choose your file for translation
2) Check that he is no longer occupied by anyone ( doc.php.net/trantools/revcheck_extended_ru.html and in the “files in progress” section on edit.php.net)
3) Translate and draw up the translation as expected (3 system tags on top, the indentation level must be 1 space - no tabs)

Important! After the end of the transfer, you must make sure that you have not broken anything, i.e. build bild This is done by the following command:

 $ php doc-base/configure.php --with-lang=ru 

If successful, the end should be All good. Saving .manual.xml ... done.
(Also at the end, Segmentation fault may crash if you use PHP <5.3.7 - there is nothing to worry about, this is a side effect of optimizing the build script speed. You can turn off the release of a segfolt, but this will lead to a slightly longer build script - list of options the build script can be seen with the command

 $ php doc-base/configure.php --help 

If the team displays something like Don't worry, Happ shittens, it means that you made a mistake and you need to fix it. For example, it may be an unclosed tag or an unknown xml entity of type & error ;. Advanced error reporting mode can be enabled by adding the option --enable-xml-details. Note that in this mode, the assembly can use much more memory.

Sending a patch

So, you have successfully translated the text and compiled the build. Since you do not have an svn account, you cannot commit your work yourself, you need to create a patch and send it to the mailing list. This is pretty easy.
The patch is created by the following command (it is advisable to execute it in the folder of the Russian repository, i.e. phpdoc-ru / ru in our example).

 $ svn diff > good-patch-name.patch.txt 

where good-patch-name is a clear patch name that describes what you translated. Also note the txt extension - the mailing list will not accept your patch if you specify another extension.
After that, you need to write a letter to the mailing list and attach to it the created patch. Everything! :)

You can later update the repository with the command

 $ svn up 

which should also be run from the repository root (phpdoc-ru).

Afterword

Article prepared: conf , irker . If you find a typo or error in the article, please write me a private message about them.

Upd: Chat translators in slack