diff --git a/tutorial/editing.md b/tutorial/editing.md index 4d608b1..40684c0 100644 --- a/tutorial/editing.md +++ b/tutorial/editing.md @@ -27,86 +27,7 @@ The `docgen` script is found within the PHP documentation (phpdoc/scripts/docgen documentation (DocBook) files. Fill in skeleton files before you commit them! ## Translating documentation -Translating documentation into other languages might look like a complicated process, but in fact, it's rather simple. -Every file in SVN has *revision*. It is basically current version of specified file. We use revisions to check if file -is synchronized with English version, so to find out if translation is up-to-date. That's why every file in your -translation requires EN-Revision comment with following syntax: -`` -The most important part of this comment is revision of English file which translated version is based on. Let's see -examples: - -### Translating new file -You want to translate documentation of `in_array()` function, which doesn't exists in your language yet. Open the file -`phpdoc/en/reference/array/in-array.xml` and copy number of revision. Sample header might look like this: -``` - - -``` - -So our number is `310394`. Let's see how your translated file header should look like if we assume that your SVN -username is *johnsmith*: -``` - - - -``` - -`$Revision` is a kind of macro which will be replaced with number of current revision when you commit your changes. -Revision number you have copied from english file was created this way. - -The rule is simple: if your revision number is equal to revision number of english file you've translated, it means -that your translation is up-to-date. Otherwise, it needs to be synced. - -### Updating translation of existing file -Let's assume you want to update translation of `password_needs_rehash()`. There are two simple ways -to see which files require update and what have to be changed to sync with English version: using -[Online Editor](http://doc.php.net) or [doc.php.net tools](http://doc.php.net). Second way is described below. - -Choose your language from right sidebar and then use "Outdated files" tool. Filter files by directory or username -(username used here comes from `Mantainer` variable in comment described above). Let's assume that script marked -`password-needs-rehash.xml` as outdated. Click on filename and you will see *diff* - list of changes between two -versions of file: your version (current number in EN-Revision in your translation) and newest version in English -tree. This is sample diff: - -``` ---- phpdoc/en/trunk/reference/password/functions/password-needs-rehash.xml 2013/06/21 12:24:55 330609 -+++ phpdoc/en/trunk/reference/password/functions/password-needs-rehash.xml 2014/03/24 20:23:27 333093 -@@ -12,8 +12,8 @@ - - booleanpassword_needs_rehash - stringhash -- stringalgo -- stringoptions -+ integeralgo -+ arrayoptions - - - This function checks to see if the supplied hash implements the algorithm -``` - -First two lines indicate compared revisions. First was taken from your EN-Revision tag and second is current version -of this file in English. As you can see, there is a difference between two lines. Types of parameters `options` and -`algo` in function synopsis had been changed from `string` to `integer` and `array`. You have to perform this changes -in your translation to make it up-to-date. Open `phpdoc/{LANG}/reference/password/functions/password-needs-rehash.xml` -and change those lines to match English version. - -Then update EN-Revision number in header. You can also add your credits using CREDITS tag. Your file header might look like this: -``` - - - -``` -and after changes it should looke like this: -``` - - - - -``` -Numbers came from diff showed above. If you want to add yourself to credits tag which already exists, separate -usernames with coma, i.e.: ``. - -Finally, your translation is up-to-date. It is quite long process but it's simple and logical when you get used to. +Translation process has been described in [separate chapter](translating.md). ## Validating your changes Every time you make changes to documentation sources (both English or translation) you have to validate your changes. diff --git a/tutorial/translating.md b/tutorial/translating.md new file mode 100644 index 0000000..d41b93f --- /dev/null +++ b/tutorial/translating.md @@ -0,0 +1,85 @@ +# Translating documentation + +**Watch out:** this chapter describes special part of whole editing process. You have to follow other steps from +[editing manual sources](editing.md) section. + +Translating documentation into other languages might look like a complicated process, but in fact, it's rather simple. +Every file in SVN has *revision*. It is basically current version of specified file. We use revisions to check if file +is synchronized with English version, so to find out if translation is up-to-date. That's why every file in your +translation requires EN-Revision comment with following syntax: +`` +The most important part of this comment is revision of English file which translated version is based on. Let's see +examples: + +## Translating new file +You want to translate documentation of `in_array()` function, which doesn't exists in your language yet. Open the file +`phpdoc/en/reference/array/in-array.xml` and copy number of revision. Sample header might look like this: +``` + + +``` + +So our number is `310394`. Let's see how your translated file header should look like if we assume that your SVN +username is *johnsmith*: +``` + + + +``` + +`$Revision` is a kind of macro which will be replaced with number of current revision when you commit your changes. +Revision number you have copied from english file was created this way. + +The rule is simple: if your revision number is equal to revision number of english file you've translated, it means +that your translation is up-to-date. Otherwise, it needs to be synced. + +## Updating translation of existing file +Let's assume you want to update translation of `password_needs_rehash()`. There are two simple ways +to see which files require update and what have to be changed to sync with English version: using +[Online Editor](https://edit.php.net) or [doc.php.net tools](http://doc.php.net). Second way is described below. + +Choose your language from right sidebar and then use "Outdated files" tool. Filter files by directory or username +(username used here comes from `Mantainer` variable in comment described above). Let's assume that script marked +`password-needs-rehash.xml` as outdated. Click on filename and you will see *diff* - list of changes between two +versions of file: your version (current number in EN-Revision in your translation) and newest version in English +tree. This is sample diff: + +``` +--- phpdoc/en/trunk/reference/password/functions/password-needs-rehash.xml 2013/06/21 12:24:55 330609 ++++ phpdoc/en/trunk/reference/password/functions/password-needs-rehash.xml 2014/03/24 20:23:27 333093 +@@ -12,8 +12,8 @@ + + booleanpassword_needs_rehash + stringhash +- stringalgo +- stringoptions ++ integeralgo ++ arrayoptions + + + This function checks to see if the supplied hash implements the algorithm +``` + +First two lines indicate compared revisions. First was taken from your EN-Revision tag and second is current version +of this file in English. As you can see, there is a difference between two lines. Types of parameters `options` and +`algo` in function synopsis had been changed from `string` to `integer` and `array`. You have to perform this changes +in your translation to make it up-to-date. Open `phpdoc/{LANG}/reference/password/functions/password-needs-rehash.xml` +and change those lines to match English version. + +Then update EN-Revision number in header. You can also add your credits using CREDITS tag. Your file header might look like this: +``` + + + +``` +and after changes it should looke like this: +``` + + + + +``` +Numbers came from diff showed above. If you want to add yourself to credits tag which already exists, separate +usernames with coma, i.e.: ``. + +Finally, your translation is up-to-date. It is quite long process but it's simple and logical when you get used to. \ No newline at end of file