doc/i18n.html

   1 <!--
   2  *Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  *Copyright (C) $$Year-Rel$$ The Jalview Authors
   4  *
   5  *This file is part of Jalview.
   6  *
   7  *Jalview is free software: you can redistribute it and/or
   8  *modify it under the terms of the GNU General Public License
   9  *as published by the Free Software Foundation, either version 3
  10  *of the License, or (at your option) any later version.
  11  *
  12  *Jalview is distributed in the hope that it will be useful, but
  13  *WITHOUT ANY WARRANTY; without even the implied warranty
  14  *of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  *PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  *You should have received a copy of the GNU General Public License
  18  *along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  *The Jalview Authors are detailed in the 'AUTHORS' file.
  20 -->
  21 <!DOCTYPE html SYSTEM "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  22 <!--
  23  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8)
  24  * Copyright (C) 2012 J Procter, AM Waterhouse, LM Lui, J Engelhardt, G Barton, M Clamp, S Searle
  25  *
  26  * This file is part of Jalview.
  27  *
  28  * Jalview is free software: you can redistribute it and/or
  29  * modify it under the terms of the GNU General Public License
  30  * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  31  *
  32  * Jalview is distributed in the hope that it will be useful, but
  33  * WITHOUT ANY WARRANTY; without even the implied warranty
  34  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  35  * PURPOSE.  See the GNU General Public License for more details.
  36  *
  37  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  38 -->
  39 <html xmlns="http://www.w3.org/1999/xhtml">
  40   <head>Jalview i18n</head>
  41   <body>
  42 <h1>Best practices</h1>
  43 <ol>
  44 <li>Follow the standards described in this guide</li>
  45 <li>Always use properties files for user interface text; never include displayable text in code</li>
  46 <li>Use properties files only for user interface text (Messages_xx.properties) and config files for configuration settings (jalview.properties).</li>
  47 <li>Use a proper naming schema for keys in your resource bundles. The name of the keys should provide some information about the context of the displayed text. This helps the translators during the translation process.</li>
  48 <li>Group keys by view, ie. edit.title, edit.instructions, list.title, list.instructions, create.title, etc</li>
  49 <li>Never use displayable text when executing comparisons within the logic of the tool (separate codified values from displayable text)</li>
  50 <li>Always use the MessageManager class for retrieving properties values, and invoke MessageManager methods dynamically, to accommodate dynamic user preferences (see MessageManager below).</li>
  51 <li>All numbers and dates should be formatted specific to the user's locale (e.g. java.text.NumberFormat and java.text.DateFormat)</li>
  52 <li>Test code in more than one language</li>
  53 </ol>
  54 <h1>MessageManager</h1>
  55 <p>The jalview.util.MessageManager class is a wrapper class for the ResourceBundle class. It provides dynamic language/locale support for individual users, and is recommended for all Jalview code.</p>
  56 <p>To use it within your code, you only have to invoke MessageManager with the text key in Messages_xx.properties:</p>
  57 <p>JButton ok = new JButton(MessageManager.getString("button.ok"));</p>
  58 <p>This will set JButton text to the one included at button.ok key. In English JButton text will be OK, while in Spanish will be Aceptar. This is the big thing of i18n. :)</p>
  59 <h1>Don't rely comparisons on labels</h1>
  60 <p>Don't use this type of coding:
  61     threshold.addItem("No Threshold");<br>
  62     threshold.addItem("Above Threshold");<br>
  63     threshold.addItem("Below Threshold");<br>
  64     [...]<br>
  65     if (threshold.getSelectedItem().equals("Above Threshold"))<br>
  66     {</br>
  67       aboveThreshold = AnnotationColourGradient.ABOVE_THRESHOLD;<br>
  68     }<br>
  69     else if (threshold.getSelectedItem().equals("Below Threshold"))<br>
  70     {<br>
  71       aboveThreshold = AnnotationColourGradient.BELOW_THRESHOLD;<br>
  72     }<br>
  73 </p>
  74 <p>Once text has been translated, these equals will fail as the label won't be the English ones. It should be used getSelectedIndex() instead of getSelectedItem(). If you do the proper way, the code will look like this:<br>
  75     threshold.addItem(MessageManager.getString("label.threshold_feature_no_thereshold"));<br>
  76     threshold.addItem(MessageManager.getString("label.threshold_feature_above_thereshold"));<br>
  77     threshold.addItem(MessageManager.getString("label.threshold_feature_below_thereshold"));<br>
  78     [...]<br>
  79     if (threshold.getSelectedIndex()==1)<br>
  80     {<br>
  81       aboveThreshold = AnnotationColourGradient.ABOVE_THRESHOLD;<br>
  82     }<br>
  83     else if (threshold.getSelectedIndex()==2)<br>
  84     {<br>
  85       aboveThreshold = AnnotationColourGradient.BELOW_THRESHOLD;<br>
  86     }<br>
  87 </p>
  88 <h1>How to translate Jalview</h1>
  89 <p>Anyone interested in localizing/translating Jalview is strongly encouraged to join the <a href="mailto:jalview-dev@jalview.org">Jalview Development List</a> list. We would recommend that you read this entire page before proceeding.</p>
  90 <p>If you are planning on working on a Jalview translation, please send us an email (<a href="mailto:jalview-dev@jalview.org">Jalview Development List</a>). There may be someone else already working on translating Jalview to your target language.</p>
  91 <p>Once you have downloaded the source code (available at <a href="http://www.jalview.org/download">http://www.jalview.org/download</a>), you must edit {jalview.home}/resources/lang/Messages_xx.properties, where xx refers to your language country code. If it doesn't exits, rename Messages.properties to Messages_xx.properties.</p>
  92 <p>Next step...start transtalation!</p>
  93 <p>Once you have it translated, we would appreciate if you contribute it forwarding the file to <a href="mailto:jalview-dev@jalview.org">Jalview Development List</a>. We will commit it to the code base as soon as possible. Thanks so much for this in advance!</p>
  94 </body>
  95 </html>
  96