From AbiWiki

Revision as of 04:26, 24 November 2010

Page Is Unavailable Due To Site Maintenance, Please Visit Reserve Copy Page

<h2 dir="ltr">New AbiWord Translation</h2>

<p>These instructions will allow you to translate AbiWord for a language that does not have an existing translation yet.</p>

<p>Before you start, make sure that you have SVN and Perl installed on your computer.

<h3>Step 1: Download AbiWord via SVN</h3>

<p>There are Instructions for using SVN to download AbiWord's source code.</p>

<blockquote><code>

    $ svn co http://svn.abisource.com/abiword/trunk abiword

</code></blockquote>

<h3>Step 2: Build a New Translation File</h3>

<p>You need a build a file called abiword.pot which is basically a blank translation of AbiWord's strings.</p>

<p>To do this, go into the <strong>abiword/po</strong> directory and run the "update.pl" script as follows:</p>

<blockquote><code> $ ./update.pl --pot </code></blockquote>

<p>This should produce the file <strong>abiword.pot</strong>.</p>

<p> Now you are ready to make the new translation file for your language. All you need to do is rename <strong>abiword.pot</strong> to the form <strong><em>xx-YY</em>.po</strong> where <em><strong>xx</strong></em> or <em><strong>xxx</strong></em> is your ISO language code and <em><strong>YY</strong></em>

is your ISO country code. For example, fr-FR is French, pt-BR is Brazilian Portuguese, and arn-CL is Mapudungun from Chile. (If you don't know the ISO code for your language, look here and here and see this list of ISO county codes.)</p>

<blockquote><code> $ mv abiword.pot xx-YY.po </code></blockquote>

<h3>Step 3: Translate xx-YY.po</h3>

<p>Each phrase to translate in the file <strong><em>xx-YY</em>.po</strong> will appear in this format:</p>

<blockquote><code>

   WHITE-SPACE<br />
   #  TRANSLATOR-COMMENTS<br />
   #. AUTOMATIC-COMMENTS<br />
   #: REFERENCE...<br />
   #, FLAG...<br />
   msgid UNTRANSLATED-STRING<br />
   msgstr TRANSLATED-STRING

</code></blockquote>

<p>The important elements are the <b>msgid</b> which contains the orignal phrase in English and the <b>msgstr</b> which contains the translated phrase. You only need to change the <b>msgstr</b>. For example, if you are translating the msgid "Cancel" into Spanish, you would only need to change from this:</p>

<blockquote><code>

   #. DLG_Cancel<br />
   #: po/tmp/xap_String_Id.h.h:127<br />
   msgid "Cancel"<br />
   msgstr ""<br />

</code></blockquote>

<p>To this:</p>

<blockquote><code>

  #. DLG_Cancel<br />
  #: po/tmp/xap_String_Id.h.h:127<br />
  msgid "Cancel"<br />
  msgstr "Cancelar"<br />

</code></blockquote>

<p>If you are unsure how to translate a string, it is good idea to mark it with a "fuzzy" flag and leave a comment for the next translator to check it. For instance if you don't know whether to translate "Cancel" as "Cancelar" or "Anular", you could change this entry to:</p>

<blockquote><code>

   #  Should it be "Cancelar" or "Anular"?<br />
   #. DLG_Cancel<br />
   #: po/tmp/xap_String_Id.h.h:127<br />
   #, fuzzy<br />
   msgid "Cancel"<br />
   msgstr "Cancelar"<br />

</code></blockquote>

<p>Strings which contain a <strong>"&amp;"</strong> or <strong>"&amp;amp;"</strong> can be accessed with a key press in a menu or a dialog box. The character following the <strong>&amp;</strong> or <strong>"&amp;amp;"</strong> will be underlined to tell the user which key to press.</p>

<p>For example, the menu item "&amp;Header" would appear as "<u>H</u>eader" and can be reached by pressing <b>H</b> or <b>Alt + H</b>. The Spanish translation of "Header" is "Cabecera", so the strings would look like this:</p>

<blockquote><code>

   msgid "&amp;Header"<br />
   msgstr "&amp;amp;Cabecera"

</code></blockquote>

<p>Only underline one character per menu item and avoid chosing thin characters such as 'i' or 'l' because it will be difficult for the AbiWord user to see that these characters are underlined. Also avoid underlining characters such as 'j' and 'y' whose strokes are lower than normal letters and difficult to read when underlined.</p>

<p>Long strings that are difficult to read can be broken into multiple lines by enclosed extra lines in double quotation marks. Breaking the string into multiple lines will have no effect on the final string, since the computer will strip away any spaces and hard returns outside of the quotation marks. </p>

<p>If you want to put double quotation marks inside a string, use the escape code <b>\"</b>&nbsp;&nbsp; The escape code <b>\n</b> adds a hard return to a string and <b>\t</b> adds a tab. As a general rule, only add these escape codes to the <b>msgstr</b> if they are found in the <b>msgid</b>. If you see <b>%s</b> or <b>%d</b> in the <b>msgid</b>, that indicates that a string variable or a numerical variable will be inserted into the string at that point. Make sure that the <b>msgstr</b> contains the same number of these variables as are found in the <b>msgid</b>.</p>

<p>For instance, here is a good example of a screen message with a number of escape codes and variable codes. Notice how it is broken up over several lines to make it easier to read and each line is enclosed in double quotation marks:</p>

<blockquote><code> msgid ""<br /> "%s not implemented yet.\n\n"<br /> "If you are a programmer, feel free to add code in %s, line %d\n"<br /> "and mail patches to:\n\n"<br /> "\tabiword-dev@abisource.com\n\n"<br /> "Otherwise, please be patient."<br /> msgstr ""<br /> "%s todaví­a no está implementado.\n\n"<br /> "Si usted es un programador, siéntase libre para añadir código en %s, lí­nea %d\n"<br />

"y enviar parches a:\n\n"<br /> "\tabiword-dev@abisource.com\n\n"<br /> "En otro caso, tenga paciencia." </code></blockquote>

<p>You can edit the file <b><i>xx-YY</i>.po</b> with any text editor so long as you save it in the same character encoding which is listed in the header of the PO file. It is best to use UTF-8 (8-bit Unicode) encoding. To avoid syntax errors, use a text editor that recognizes source code such as emacs, vim, gedit, or kate so that you can see when you improperly terminated a string or forgot to enclose it in double quotation marks. Notepad++ is a good text editor for Windows users. (Set "Language" to "C" and mark "Encode in UTF-8" under "Format").</p>

<p>Some people prefer to use special translation software such as KBabel or poedit which has translation memory so you only have to translate a phrase once. These programs also help you maintain a consistant translation for every instance of a word. If multiple people will be working on the translation, it may be easier to use a web-based PO translator such as Pootle.</p>

<p>If you are translating in a language which borrows a lot of frases from another language, you can use the script instrans.php to insert translations from that other language. For example many indigenous language in Latin America use Spanish frases for computer terminology. &nbsp;A translator can leave these terms blank and use&nbsp;instrans.php to insert the Spanish frases in the PO file. In addition, people who can't read English or want to see the translation in a third language can use instrans with the --comment option to insert the translations from another language in the comment field in the PO file. For instance, translators of Quechua (an indigenous language of the Andes) often want to see the translation in Spanish before translating into Quechua.</p>

<h3>Step 4: Check the Translation</h3>

<p>After you have finished your translation, you should check how it will appear in AbiWord. In order to test your translation you will have to convert it from a <b>.po</b> file to a <b>.string</b> file with the perl script <b>ui-backport.pl</b>. Go to the <b>abiword/po</b> directory and issue the command:</p>

<blockquote><code> $ ./ui-backport.pl xx-YY </code></blockquote>

<p>This script will create a file called <b><i> xx.YY</i>.string</b> in the directory <b>abiword/user/wp/strings</b>. If you have downloaded the complete source code you can compile and install AbiWord now and see if your translation worked. Instead, you may also test your translation with an existing installation of AbiWord. Find the <b>AbiWord/strings</b> directory in your installed copy of AbiWord. On Linux/UNIX you will typically find it at

<b>/usr/share/AbiSuite-2.<i>X</i>/AbiWord/strings</b> and in Windows at <b>c:\Program Files\AbiSuite2\Abiword\strings</b>. In Linux/UNIX/OS X you can find your string file with the locate command:</p>

<blockquote><code>

$ updatedb<br />
$ locate xx-YY.string

</code></blockquote>

<p>Now replace the existing .string file with the one that you just created. Rename the existing xx-YY.string file to xx.YY.string.old and then copy your new .string file from the directory <b>abi/user/wp/strings</b> to <b>AbiWord/strings</b>. If you have <b>abiword</b> trunk checked out in the <b>home/user</b> directory, the commands would be:</p>

<blockquote><code>

$ su<br />
&nbsp;&nbsp;&nbsp;&nbsp;<i>enter the root password</i><br />
# cd /usr/share/AbiSuite-2.X/AbiWord/strings<br />
# mv xx-YY.strings xx-YY.strings.old<br />
# cp /home/user/abi/user/wp/strings/xx-YY.strings ./<br />
# exit

</code></blockquote>

<p>If you are using Windows, start up AbiWord and go to <b>Tools</b>-&gt;<b>Preferences</b> and change the <b>"User Interface Language"</b> to your language. After you quit and restart AbiWord, the program should using your new translation. If you are starting a new translation of AbiWord, then AbiWord probably doesn't recognize your language because it doesn't have a language code for it yet. You can still test your translation by renaming your .strings file to an existing .strings file with a different language code. For instance, you could rename it as pt-BR.strings and then select Brazilian Portuguese as your user interface language to see your translation in AbiWord </p>

<p>To order to run AbiWord with your translation in Linux/UNIX/OS X, your locale needs to be set to your translation language. Check what language you are currently in:</p>

<blockquote><code> $ locale </code></blockquote>

<p>If your locale doesn't match the language of your .string file, change it to match:</p>

<blockquote><code> $ LANG=xx_YY.UTF-8<br /> $ export LANG </code></blockquote>

<p>Now run AbiWord. If AbiWord starts up in English, then there is probably something wrong with your PO file. Check that all the strings terminate in double quotation marks and that the number of <b>%s</b> and <b>%d</b> codes in the <b>msgid</b> matches the number in <b>msgstr</b>.</p>

<p>Open all the dialog boxes in AbiWord and make sure that your translations fit in the available space. You may have to use shorter phrases to fit in the buttons. Check each menu and submenu to see whether each menu item can be accessed with a key press and no shortcut character has been assigned to more than one item in a menu. Also check to see that the underlined character is easy to see for each menu item. Check the shortcut characters in dialog boxes as well.</p>

<p>If possible you should check your translation in both Windows and Linus/UNIX because many of the dialog boxes such as "Preferences" are not the same in different operating systems.</p>

<p>Don't worry if you see some of the standard buttons in dialog boxes in a different language other than your translation. In some of its dialog boxes AbiWord is using standard system buttons whose appearance isn't controlled by xx-YY.strings file. In Windows, these buttons will appear in the language of the operating system. Since Windows Unicode Port is in progress, you may find some of the dialogs in incomplete state in Windows. In Linux/UNIX your standard system buttons will default to English if your system doesn't recognize your language or have a translation for your language. This can be a very annoying feature if you are working with a minority language like Quechua or Basque where you would prefer the buttons to default to a different language like Spanish, but there is nothing that you can do about it.</p>

When you have finished using AbiWord, remember to return your system to its original language using LANG and export.

<h3>Step 5: Submit the Translation</h3>

<p>After you have translated and tested your translation, please send your xx-YY.po file to the developer's mailing list so that we can incorporate your translation into the project. Please zip the attachment before sending it, as that will be more convenient for users on slow internet connections, and to prevent it from being marked as spam my our mail server.</p>

<p>You can subscribe to the mailing list by sending an email to abiword-dev-request@abisource.com with the word "subscribe" in the mesage body. Once you're subscribed, you can send an email to abiword-dev@abisource.com and attach your translation. Please zip or gzip your attachment before sending it, otherwise it might be too large or marked as spam.</p>

<p>If you started translating your xx-YY.po file several months ago, you may want to update it before submitting it to be included in the project source code. In a couple months time, some of the original msgid strings may have changed and new ones may have been added.</p>

<p>To update your <b>xx-YY.po</b> file, take an svn update on the abiword <b>trunk</b> and copy your <b>xx.YY.po</b> file into the <b>abiword/po</b> directory. Then run the <b>update.pl</b> script to check for changes:</p>

<blockquote><code> $ ./update.pl xx-YY </code></blockquote>

<p>The <b>update.pl</b> script will not only add any new strings to be translated, it will also mark any changed strings with a "fuzzy" flag. You can do a search for the word "fuzzy" to find these changed strings, so you can change them before submitting your translation.</p>