View source for Internationalisation

{{Jmol Development Sections}}
= Jmol Internationalisation and Localisation =

{{Lang:Internationalisation}}

'''`InternationalisationÂ´''' is the process of designing software so that it can be adapted to various languages and regions without engineering changes. '''`LocalisationÂ´''' is the process of adapting software for a specific region or language by adding locale-specific components and translating text.

__TOC__

= Internationalisation =

:''This is meant for developers only''

== Application and Applet ==

In Jmol version 10.00.12 we changed from an unhandy (but well-known) translation process to a more powerful one using [http://www.gnu.org/software/gettext/gettext.html GNU's gettext] suite. The localisation section below contains a detailed explanation of this process. More documentation is available in [http://www.gnu.org/software/gettext/manual/ the gettext manual].

=== Coding ===
All text fragments are called in the code like this:
 GT._("Here the English text")
:''Special case:''
:When the text includes a variable word or phrase that comes from an external source (somewhere else in the code, which changes depending on the current situation), you should account for it in this way:
 GT._("Here the number {0} English text",someVariable)
:The value of ''someVariable'' will be inserted at the position of ''{0}'', so it might render, e.g., as
:: Here the number 1 English text
:: Here the number 2 English text
:: etc.
:This is needed since the position of that word may be different in different languages. Translators should leave the {0} token as is but put it in the proper place. For example, Spanish translation would be:
:: <code>"AquÃ va el texto en espaÃ±ol nÃºmero {0}"</code>
:: AquÃ va el texto en espaÃ±ol nÃºmero 1
:: AquÃ va el texto en espaÃ±ol nÃºmero 2
:: etc.
: If more than one such words are needed, use {0}, {1}, etc., and the code changes a little bit, like in:
 GT._("The user {0} has an id of {1} for this session.",
 new String[]{ userName,sessID })

= Localisation =

Several pieces of Jmol can be translated into your local language:

You can check the [[Internationalisation/Current_Status|current status of translations]].

<br />
== Translating this Wiki ==

The articles in this Wiki can be translated into your own language.

The explanation below will take two different situations:
* When the page you want to translate is already translated into an other language.
* When the page you want to translate is not translated into any other language.

We will suppose in the explanation that you want to translate a page named English_Page into XXXXX (language code: xx).



=== Page already translated into another language ===

* In the [http://wiki.jmol.org/index.php?title=Special%3AAllpages&from=&namespace=10 Template namespace], edit the existing page <tt>Lang:English_Page</tt>, add your language in it and save the page:
 <nowiki>----
{| border="0" cellspacing="1"
|-
! valign="middle" | [[Image:Geographylogo.png]]
| valign="middle" align="left" | <span style="font-size:smaller">
Reference:
'''[[English_Page|English]]''' â 
Other:
<!--es-->[[English_Page/es|EspaÃ±ol]] Â· 
<!--fr-->[[English_Page/fr|FranÃ§ais]] Â· 
<!--xx-->[[English_Page/xx|XXXXX]] Â· 
</span>
|}
----</nowiki>
* Edit the <tt>English_Page</tt> to have the source code of the page, copy the entire source code (<tt>Ctrl+A</tt>, <tt>Ctrl+C</tt>) and cancel the page editing.
* Start editing the page in your language (<tt>English_Page/xx</tt>), paste the source code (<tt>Ctrl+V</tt>) and then translate the page.


=== Page not translated into any other languages ===

* Edit the template page (<tt>Template:Lang:English_Page</tt>) and initialize it:
 <nowiki>----
{| border="0" cellspacing="1"
|-
! valign="middle" | [[Image:Geographylogo.png]]
| valign="middle" align="left" | <span style="font-size:smaller">
Reference:
'''[[English_Page|English]]''' â 
Other:
<!--xx-->[[English_Page/xx|XXXXX]] Â· 
</span>
|}
----</nowiki>
* Edit the <tt>English_Page</tt>, insert <tt><nowiki>{{Lang:English_Page}}</nowiki></tt> at the beginning, copy the entire source code (<tt>Ctrl+A</tt>, <tt>Ctrl+C</tt>) and save the page.
* Start editing the page in your language (<tt>English_Page/xx</tt>), paste the source code (<tt>Ctrl+V</tt>) and then translate the page.

<br />
== Translating the application/applet ==

See the [[Internationalisation/Current_Status|current status]] of the translations.

Participating in the translation of the application or the applet can be achieved in several ways:
{{:Internationalisation/Online}}
{{:Internationalisation/Offline}}
* A few items in the application cannot be translated by any of these two methods, and need a special procedure. See [[Internationalisation/Translating_html_files|Translating html files]].

=== Translation of the ''Export to Web'' module ===

Although this module is part of the application, and therefore instructions above are applicable, there are some special characteristics that call for some precautions and a partially different procedure.

* See [[Internationalisation/Offline/Export_to_Web|Translating the Export to Web module]].

<br />

== Translating the Applet-, User- and Developers-Guide ==

The guides are written in XML. ...


1. First install and download:
* [http://www.python.org/download/ Python] runtime
* [ftp://xmlsoft.org/ libxml2-python] bindings ([http://users.skynet.be/sbi/libxml-python/ Windows-port])
* [http://www.gnu.org/software/gettext/gettext.html gettext] ([http://gnuwin32.sourceforge.net/packages/gettext.htm Windows-port]) - see also the first paragraphs in Translating the application/applet
* [http://ftp.gnome.org/pub/GNOME/sources/gnome-doc-utils/ gnome-doc-utils] - '''only''' Linux users, the Python scripts in Jmol-HEAD\doc\source are ('''only!''') for Windows users

'''Linux users:''' you should '''ALWAYS''' try to use youir package management to install (software-)packages.

'''Windows users:''' you '''MUST''' add an environment variable <tt>PYTHON_PATH</tt>, which contains the directory where you installed Python, e.g. <tt>set PYTHON_PATH=C:\Program Files\Python24</tt>.

Now you are done with the prerequisites.


2. All targets related to internationalisation and localisation of the documentation are part of {{File|build-doc-i18n.xml}}. To create PO-template files, run <tt>ant -f build-doc-i18n.xml create-pot</tt>. All {{File|Jmol*Guide.''LANG''.po}} files (which contain the translation and are maintained by the translator himself) are updated with <tt>ant -f build-doc-i18n.xml update-po</tt>. To create the final (translated) XML file {{File|Jmol*Guide_''LANG''.docbook.xml}}, run <tt>ant -f build-doc-i18n.xml update-xml</tt>.


3. To create a translation in your language, go to {{Directory|doc/source/po}} and copy {{File|Jmol*Guide.pot}} to {{File|Jmol*Guide.''LANG''.po}} - <tt>''LANG''</tt> means your language code: e.g. <tt>de</tt> for German, <tt>fr</tt> for French and so on.


4. The rest is similar to the above Howto.


<br />
== Translating the Jmol and FAH websites ==

... to write