New PHP documentation translation tool: edit.php.net

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 "The PHP Documentation Translation Team Needs Help ."
UPD : The site may lag due to the habra effect.

---

On each page of the manual there is a link for editing it in edit.php.net.

By clicking on it we will get to the authentication page, where immediately without hesitation we choose the language Russian for translation.

Then we recommend that you immediately log in using your google or facebook account, this will allow you to work on the translation under one login from different computers. (Otherwise, a temporary Anonymous account #xxxx is created). To do this, first confirm your google or facebook account on the right, and then click Use this credentials and Anonymous Login.

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

1) Choose what to translate: Untranslated files or non-updated files. Or you can select files for verification from the “files for proofreading” 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, then you will also see its English version and changes in it compared to the old version.

At the beginning of each file with a finished translation, three special tags are required

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 ru-doc responsible participant).
Example: there is a tag in an English file , add a tag to the Russian file .

The second tag indicates that additional proofreading will not hurt this file - it is always useful to look at the translation for several people. If you checked the “file for proofreading”, then you can put this tag value Reviewed: yes. (i.e., if no one has double-checked the translation, and if they double-checked)

The last tag is technical, it will include a revision of the translated file.
Those. it’s enough that he simply was, for example, without a number at all .

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 needs to be done necessarily - he indicates to us that you have finished translating the file!


As you can see, there are 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 quickly consider patches. We also undertake to indicate your nickname at every commit patch as the author or participant of the file translation - each person’s work is valuable and there is no sense in not talking about it.

Tips:
- Save yourself more often, anything happens and it will be a pity to lose your work.
- Group files into patches within the meaning. For example, if you have translated several documentation files to an extension, it makes sense to add them to one patch with the name of this extension.

I ask you to take into account in advance that we are few in number 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 there was an svn repository. Rather, it was not, but it is. In essence, 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 uncomfortable for you, you have your own cool editor or IDE, in which your productivity just goes through the roof. Well, or just 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 running from the command line (also known as php cli).

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

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

• doc-base (system scripts for translation assembly)
• en (original version of 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 via a similar link, svn.php.net/viewvc/phpdoc/modules/doc-ru where the repository is replaced by 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 a file for translation
2) Check that it 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 execute the translation as it should (3 system tags on top, the indent level should be 1 space - no tabs)

Important! After the translation is completed, you need to make sure that you did not break anything, i.e. build a build. This is done with the following command:

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

If successful, the conclusion should be All good. Saving .manual.xml ... done.
(Also, at the end, a 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 speed of the build script. You can disable segfault, but this will lead to a slightly longer build script operation - list of options build script can be seen with the command

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

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

Sending a patch

So, you successfully translated the text and collected 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 the friendly name of the patch that describes what you translated. Pay attention also to 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 the created patch to it. All! :) You

can subsequently update the repository with the command

$ svn up

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

Afterword

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

Upd: Chat translators in slack