[or-cvs] r20308: {translation} updated howto (translation/trunk/tools/gsoc09)

[runa@xxxxxxxx]

Author: runa
Date: 2009-08-15 09:23:24 -0400 (Sat, 15 Aug 2009)
New Revision: 20308

Modified:
   translation/trunk/tools/gsoc09/HOWTO
Log:
updated howto

Modified: translation/trunk/tools/gsoc09/HOWTO
===================================================================
--- translation/trunk/tools/gsoc09/HOWTO	2009-08-15 12:32:27 UTC (rev 20307)
+++ translation/trunk/tools/gsoc09/HOWTO	2009-08-15 13:23:24 UTC (rev 20308)
@@ -22,11 +22,8 @@
 bunch of .pot (po-template) files, Pootle can generate the .po files
 needed for all supported languages. See http://translation.torproject.org/
 
-1. Update the translations
---------------------------
+Before you get to work, you will need to check out a copy of the website:
 
-First you will need to check out a copy of the website:
-
 	svn co https://tor-svn.freehaven.net/svn/website/trunk website
 
 You also need a copy of all the translations:
@@ -42,6 +39,57 @@
 More information about the scripts and what to do if something goes
 wrong can be found in translation/tools/gsoc09/README.
 
+1. Convert existing translations
+--------------------------------
+
+You will need to use po4a-gettextize to convert a .wml, that has already
+been translated, to .po.
+
+Lets say that you have the file en-tor.wml and the German translation
+de-tor.wml. You want to convert the German translation into .po so that
+it can be read by Pootle. The following command will convert the file:
+
+	po4a-gettextize -f wml -m en-tor.wml -l de-tor.wml -p de-tor.po -M utf-8 -L utf-8
+
+The tool, po4a-gettextize, will simply match the Nth string of the
+translated file with the Nth string of the original file. If the strings
+do not match, po4a-gettextize will exit with an error. That's why it
+is important that both files share exactly the same structure.
+
+You will have to define any custom tags that the .wml files contain.
+Lets say that both files contain the custom tag <version-stable>. The
+following command will convert the file and not complain about the
+custom tag:
+
+	po4a-gettextize -f wml -m en-tor.wml -l de-tor.wml -p de-tor.po -M utf-8 -L utf-8 -o customtag="<version-stable>"
+
+If po4a-gettextize exits with an error saying that a tag has not been
+closed (and you have defined all custom tags), you will have to close
+the tag and try again. If the tag is one of those tags that you just
+don't want to close, you can define it as any other custom tag.
+
+However, there is one tag that requires more than just being defined as
+a custom tag. Lets say that the .wml files also contain an <input> tag.
+You do not want to close this, so you define it as a custom tag:
+
+	po4a-gettextize -f wml -m en-tor.wml -l de-tor.wml -p de-tor.po -M utf-8 -L utf-8 -o customtag="<version-stable> <input>"
+
+But then po4a-gettextize will complain and say that "po4a::xml: Tag
+'<input>' both in the inline and customtag categories". The solution is
+to use both the customtag and nodefault option. The nodefault option is
+for tags that poa4-gettextize should not try to set by default in any
+category. You can now convert the file with the following line:
+
+	po4a-gettextize -f wml -m en-tor.wml -l de-tor.wml -p de-tor.po -M utf-8 -L utf-8 -o customtag="<version-stable> <input>" -o nodefault="<input>"
+
+Even if po4a-gettextize manages to do its job without any problems, it
+still marks all extracted translations as fuzzy. This is to make sure
+that the translator will have a look and, hopefully, detect any
+remaining problems.
+
+2. Update the translations
+--------------------------
+
 To convert new .wml files to .pot and to update existing .pot files, run
 wml2po.sh. This script will convert/update all the .wml files to .pot
 files and put them in translation/projects/website/templates. The script
@@ -60,8 +108,8 @@
 Pootle is currently running on. Use 'svn stat' to see the list of files
 that are new and/or changed, and add/commit these files manually.
 
-2. Convert the translations
----------------------------
+3. Write the translated documents
+---------------------------------
 
 People tend to forget to click on the commit button in Pootle. Before
 converting the translated .po files, force Pootle to commit everything.