tdeedu/doc/kturtle/translator-guide.docbook

<chapter id="translators">
<title>Translator's Guide to &kturtle;</title>
<para>As you probably already know, the unique feature of the &logo; programming language is that the &logo; commands are often translated to language of the programmer. This takes away a barrier for some learners to understand the basics of programming.
When translating &kturtle; to a new language some more files have to be translated in addition to the usual strings and documentation. Yet most it is autogenerated by Rafael Beccar's scripts. These scripts can be found in <userinput>tdeedu/kturtle/scripts</userinput>, the files that needs translation can be found in <userinput>tdeedu/kturtle/data</userinput>, in those directories you also find README files which contains instructions for using/translating them. 
</para>
<para>

</para>
<sect1 id="make_directory">
<title>Creating a Directory to hold the Translated Files</title>
<para>
First, you need to create a directory to store the translated files.

Create a directory called

<filename class="directory">tde-i18n/<replaceable>code</replaceable>/data/tdeedu/kturtle/</filename>

in your KDE CVS directory, where <replaceable>code</replaceable> is your country code (the 2- or 4- letter <acronym>ISO</acronym> code).  
</para>
<para>
Copy the <filename>Makefile.am</filename> file from <filename class="directory">tdeedu/kturtle/data/</filename> into this directory.  Open it using your favorite text editor, replace all instances of <quote>en_US</quote> in the file with your country code (the one used above), and save the file.
</para>
</sect1>
<sect1 id="commands_trans">
<title>How To Translate the &logo; Keywords (commands)</title>
<para>
<itemizedlist>
<listitem><para>
Copy the <filename>logokeywords.en_US.xml</filename> file from <filename class="directory">tdeedu/kturtle/data/</filename> to the directory you have just created, and rename it to <filename>logokeywords.<replaceable>code</replaceable>.xml</filename>
where <replaceable>code</replaceable> is your country code (the 2- or 4- letter <acronym>ISO</acronym> code).
</para>
</listitem>
<listitem><para>Translate the contents of the <sgmltag class="starttag">keyword</sgmltag> tag (&ie;
the information between <sgmltag class="starttag">keyword</sgmltag>
and <sgmltag class="endtag">keyword</sgmltag>) into your own language
wherever possible. Also, translate the contents of the <sgmltag class="starttag">alias</sgmltag> tag, (&ie; the information between the <sgmltag class="starttag">alias</sgmltag> and <sgmltag class="endtag">alias</sgmltag>): these are used as shortcuts for the keyword.</para>
<para>
For example, translate <quote>while</quote> in: <sgmltag class="starttag">keyword</sgmltag>while<sgmltag class="endtag">keyword</sgmltag>
</para>
<para>
Please do not translate anything else and do not translate the English words in <sgmltag class="starttag">command name="english_word"</sgmltag>: these must stay in English.
</para>
<para>
Last bit: do not change the order of this file, this is needed for Rafael Beccar's automatic translation generation scripts.
</para>
</listitem>
<listitem><para>Save your file as <acronym>UTF-8</acronym> (in &kate;, use <guimenuitem>Save As...</guimenuitem> and change to <guilabel>utf8</guilabel> in the box on the right of the file name).
</para>
</listitem>
<listitem><para>Commit your file (add your filename in the <filename>Makefile.am</filename>) or send it to Anne-Marie.
</para>
</listitem>
<listitem><para>In case of any doubt, please contact Anne-Marie Mahfouf <email>annemarie.mahfouf@free.fr</email> for more information.</para>
</listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="examples_syntax">
<title>How To Translate the Syntax Highlighting Files</title>
<para>
Translating the <filename>logohighlightstyle.en_US.xml</filename> is a breeze when using Rafael Beccar's script in <filename class="directory">tdeedu/kturtle/data/</filename>. Please make sure to read the README file in that directory.
</para>
<para>
For backward compatibility with all people who do not want to the perl scripted blessing mentioned in the previous paragraph, here the old fashioned way of doing it:
<itemizedlist>
<listitem><para>Copy the <filename>logohighlightstyle.en_US.xml</filename> file from <filename class="directory">tdeedu/kturtle/data/</filename> to the directory you created to store the translated keywords file, and rename it to <filename>logohighlightstyle.<replaceable>code</replaceable>.xml</filename>
where <replaceable>code</replaceable> is your country code (the 2- or 4- letter <acronym>ISO</acronym> code).
</para>
</listitem>
<listitem><para>In line 4 of the file, there is
<sgmltag class="starttag">language name="en_US"</sgmltag>...: here you change <quote>en_US</quote> to your language's <acronym>ISO</acronym> code (2 or 4 letters).
</para></listitem>
<listitem><para>Translate into your own language the content of the <sgmltag class="starttag">item</sgmltag> tag (&ie; the information between <sgmltag class="starttag">item</sgmltag> and <sgmltag class="endtag">item</sgmltag>). This content must match the <filename>logokeyword</filename> file.
For example, translate <quote>while</quote> in: <sgmltag class="starttag">item</sgmltag> while <sgmltag class="endtag">item</sgmltag> and leave the spaces as they are (one at the beginning and one at the end).
Please do not translate anything else.
</para></listitem>
<listitem><para>Save your file as <acronym>UTF-8</acronym> (in &kate;, use <guimenuitem>Save As...</guimenuitem> and change to <guilabel>utf8</guilabel> in the box on the right of the file name).
</para></listitem>
<listitem><para>Commit your file (add your filename in the <filename>Makefile.am</filename>) or send it to Anne-Marie.
</para></listitem>
<listitem><para>In case of any doubt, please contact Anne-Marie Mahfouf <email>annemarie.mahfouf@free.fr</email> for more information.
</para></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="examples_trans">
<title>How To Translate the Examples</title>
<para>
Again this task is simplified a lot by Rafael Beccar's script in <filename class="directory">tdeedu/kturtle/data/</filename>. Please make sure to read the README file in that directory, since some work still has to be done after the example logo files are autotranslated. 
</para>
<para>
When you followed the instructions, given in the README file that you found in the scripts directory, you should now be almost ready. Please do not forget to test the translated example logo code you created, since it is very common that an error sneaks in. Also make sure the <userinput>Makefile.am</userinput> in <filename class="directory">tde-i18n/<replaceable>code</replaceable>/data/tdeedu/kturtle/</filename> is updated according to the new files. For the Dutch the <userinput>Makefile.am</userinput> should look like this:
<screen>
txt_DATA = advertentie.logo driehoeken.logo krullen.logo tafels.logo \
bloem.logo driehoek.logo logohighlightstyle.nl.xml pijl.logo vierkanten.logo \
kleuren.logo logokeywords.nl.xml randomnaam.logo vierkant.logo
txtdir = $(kde_datadir)/kturtle/examples/nl

xml_DATA = logohighlightstyle.nl.xml
xmldir = $(kde_datadir)/katepart/syntax

keywords_DATA = logokeywords.nl.xml
keywordsdir = $(kde_datadir)/kturtle/data
EXTRA_DIST = $(txt_DATA) $(xml_DATA) $(keywords_DATA)
</screen> 
</para>
<para>
Here a description of how to do the translation WITHOUT the use of Rafael's perl scripts:
<itemizedlist>
<listitem><para>Copy the English example files from <filename class="directory">tdeedu/kturtle/data/</filename> to the directory used to store the translated keyword and hilighting files.  Translate the filenames of the examples in your directory: this will allow users to easily and quickly understand what the example is about.</para>
</listitem>
<listitem><para>Translate the keywords in the examples, using those in the <filename>logokeywords.xml</filename> for your language. The keywords file file must be done, first, before translating the examples.</para>
</listitem>
<listitem><para>Save your file as <acronym>UTF-8</acronym> (in &kate;, use <guimenuitem>Save As...</guimenuitem> and change to <guilabel>utf8</guilabel> in the box on the right of the file name)</para>
</listitem>
<listitem><para>Commit your folder (add a <filename>Makefile.am</filename> inside) or send it to Anne-Marie.</para>
</listitem>
<listitem><para>In case of any doubt, please contact Anne-Marie Mahfouf, <email>annemarie.mahfouf@free.fr</email> for more information.</para>
</listitem>
<listitem><para>Finally, if you want, you can add your own examples in this folder.</para>
</listitem>
</itemizedlist>
</para>
</sect1>

</chapter>