summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRené 'Necoro' Neumann <necoro@necoro.net>2010-04-07 03:09:09 +0200
committerRené 'Necoro' Neumann <necoro@necoro.net>2010-04-07 03:09:09 +0200
commit9752e9bdf8dade02c24b6fff08bd9fba7ac75911 (patch)
tree69b7cd2352f79e694e7f13bdbbbc243b1d5d245b
parentf8d86726986b69e7c190de94dba085b081e00e6d (diff)
downloadweb-9752e9bdf8dade02c24b6fff08bd9fba7ac75911.tar.gz
web-9752e9bdf8dade02c24b6fff08bd9fba7ac75911.tar.bz2
web-9752e9bdf8dade02c24b6fff08bd9fba7ac75911.zip
Added translating guide
-rw-r--r--templates/pages/translating.mako97
1 files changed, 97 insertions, 0 deletions
diff --git a/templates/pages/translating.mako b/templates/pages/translating.mako
new file mode 100644
index 0000000..6e76b33
--- /dev/null
+++ b/templates/pages/translating.mako
@@ -0,0 +1,97 @@
+<%!
+ title = "Translation Guide"
+%>
+<%inherit file="/page.mako" />
+
+<p>
+ Portato supports native languages. Nevertheless the translations into these languages have to be created. This page shows how to add a new translation or how to extend an existing translation.
+</p>
+
+<%self:h2>Short introduction about NLS in Linux</%self:h2>
+<p>
+ All translatable strings of a program are listed in a *.pot file. For each translation a single $LANG.po file is created, which holds each translatable string and the corresponding translation. During installation these po-files are compiled into .mo files, which are then used to get the translations during runtime.
+ If you are wondering, what is meant by $LANG: It is a code defining a language. It normally consists of two letters as defined by <a href="http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">ISO 639-1</a>, e.g. en, de, fr... If you want to differentiate between different kinds of one language, you append a modifier: en_US, en_GB, de_DE, de_AT etc.
+</p>
+
+<%self:h2>Programs you (might) need</%self:h2>
+<p>
+ The recommended program for the translation is <strong>app-i18n/poedit</strong>, however you may want to try out <strong>kde-base/kbabel</strong> or <strong>app-text/gtranslator</strong>. Another simple option would be to use your normal text editor :)
+</p>
+<p>
+ This guide will assume you are using poedit.
+</p>
+
+<%self:h2>Getting the sources</%self:h2>
+<p>
+ You do need the sources to make translations, as the installed program is not sufficient. Please see <a href="/development">the development page</a> for how to get them.
+</p>
+
+<%self:h2>Updating an incomplete translation</%self:h2>
+<p>
+ If there is a translation for your language already, then open the $LANG.po file in portato's <em>i18n/</em> directory with poedit. Select "Update from POT file" from the "Catalog" menu, then choose the messages.pot file in the <em>i18n/</em> directory. Untranslated strings will be highlighted and placed at the top of the list. Translate them and save the file!
+</p>
+
+<%self:h2>Creating a new translation</%self:h2>
+<p>
+ Open poedit and Select "New catalog from POT file" from the "File" menu, and choose the messages.pot file in portato's <em>i18n/</em> directory. Translate, then save the file (also in the i18n/ directory) as $LANG.po.
+</p>
+
+<%self:h2>Placeholders</%self:h2>
+<p>
+ The translatable strings in the messages.pot catalogue and the $LANG.po files are partially in Python's string format, partially in GTK's. The following items should be included in translated strings as placeholders for names or figures:
+</p>
+<ul>
+ <li>"%s" : string placeholder</li>
+ <li>"%d" : number placeholder</li>
+ <li>"%(days)d" : placeholder named "days", do not translate the name</li>
+ <li>pretty much anything starting with "%"</li>
+</ul>
+
+<p>
+ Html-Tags (${"<b>some_text</b>" | h}) should be kept as is and only the text in between has to be changed.<br/>
+ In addition, the underscore (_) is used to indicate that the next character will be used as the accelerator key. When the user presses "CTRL" + this key, it will perform the item's action. These are not required, but if you use them the characters chosen must all be different.
+</p>
+
+<p>Strings like "gtk-quit", "gtk-cancel" etc. must not be translated.</p>
+
+<%self:h2>Test your translation</%self:h2>
+<p>
+ Before testing, run the "pocompile" script in the portato directory, which will compile all the .po files in <em>i18n/</em> into .mo files and place them in the necessary subdirectories (<em>$LANG/LC_MESSAGES</em>):
+</p>
+<%self:hl lang="bash">
+./pocompile.sh
+</%self:hl>
+
+<p>Now you can run the local portato version in your language:</p>
+<%self:hl lang="bash">
+./portato.py
+</%self:hl>
+
+<p>If you are not seeing your language, make sure the environment variable "LANG" is set to your language code. For example, to run portato using the German translation:</p>
+<%self:hl lang="bash">
+LANG="de_DE" ./portato.py
+</%self:hl>
+
+<%self:h2>Submit your translation</%self:h2>
+<p>
+ The easiest way to submit your translation is to create a bug in the <a href="/r/bugs">bugtracker</a> or to send a mail to <a href="mailto:portato@necoro.net">portato@necoro.net</a>.
+</p>
+
+<%self:h2>I found an untranslatable string</%self:h2>
+<p>
+ Post a bug in the <a href="/r/bugs">bugtracker</a>. Include the untranslatable string and where in Portato you came across it. It's easy for us to mark the strings for translation, but we may have missed some!
+</p>
+
+<%self:h2>GUIs suck - I want to use a text editor</%self:h2>
+<p>
+ The .po files are plain text files. If you don't want to use poedit for some reason, these gettext commands might come in handy:<br/>
+ Update a .po file from the messages.pot file:
+</p>
+<%self:hl lang="bash">
+msgmerge $LANG.po messages.pot > newpofile.po
+</%self:hl>
+
+<p>Create a new .po file from the messages.pot file:</p>
+<%self:hl lang="bash">
+msginit -i messages.pot -l $LANG
+</%self:hl>