Difference between revisions of "Internationalisation"

From Jmol
Jump to navigation Jump to search
m (link to gettext manual)
(Coding: comments for translators)
Line 19: Line 19:
 
All text fragments are called in the code like this:
 
All text fragments are called in the code like this:
 
  GT._("Here the English text")
 
  GT._("Here the English text")
:''Special case:''
+
 
 +
 
 +
''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:
 
: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)
 
  GT._("Here the number {0} English text",someVariable)
Line 32: Line 34:
 
:: etc.
 
:: etc.
 
: If more than one such words are needed, use {0}, {1}, etc., and the code changes a little bit, like in:
 
: 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 })
 +
 +
 +
''Comments for translators:''
 +
:If the text isn't self explanatory for the translators, a comment can be added for helping them understanding the context.
 +
:Use Java comments with the syntax <code>/// TRANSLATORS: explanation</code> (''note the '''3''' slashes'') just before the call to <code>GT._(...)</code>.
 +
:This comments will be included in the gettext files and will be visible by translators.
 +
/// TRANSLATORS: first line of explanation
 +
/// Second line of explanation
 
  GT._("The user {0} has an id of {1} for this session.",
 
  GT._("The user {0} has an id of {1} for this session.",
 
  new String[]{ userName,sessID })
 
  new String[]{ userName,sessID })

Revision as of 09:32, 3 July 2012

Jmol/JSmol Development

Jmol Internationalisation and Localisation


Geographylogo.png

Reference: English – Other: 日本語 ·


`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.

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 GNU's gettext suite. The localisation section below contains a detailed explanation of this process. More documentation is available in 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:
"Aquí va el texto en español número {0}"
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 })


Comments for translators:

If the text isn't self explanatory for the translators, a comment can be added for helping them understanding the context.
Use Java comments with the syntax /// TRANSLATORS: explanation (note the 3 slashes) just before the call to GT._(...).
This comments will be included in the gettext files and will be visible by translators.
/// TRANSLATORS: first line of explanation
/// Second line of explanation
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 current status of translations.


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 Template namespace, edit the existing page Lang:English_Page, add your language in it and save the page:
----
{| 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>
|}
----
  • Edit the English_Page to have the source code of the page, copy the entire source code (Ctrl+A, Ctrl+C) and cancel the page editing.
  • Start editing the page in your language (English_Page/xx), paste the source code (Ctrl+V) and then translate the page.


Page not translated into any other languages

  • Edit the template page (Template:Lang:English_Page) and initialize it:
----
{| 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>
|}
----
  • Edit the English_Page, insert {{Lang:English_Page}} at the beginning, copy the entire source code (Ctrl+A, Ctrl+C) and save the page.
  • Start editing the page in your language (English_Page/xx), paste the source code (Ctrl+V) and then translate the page.


Translating the application/applet

See the current status of the translations.

Participating in the translation of the application or the applet can be achieved in several ways:


Geographylogo.png

Reference: English – Other: 日本語 ·


  • Online: by editing directly the translation through Launchpad web site. You just need to register but no installation is required.
    • Description needs to be completed when everything is setup on the Launchpad web site

Geographylogo.png

Reference: English – Other: 日本語 ·


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.


Translating the Applet-, User- and Developers-Guide

The guides are written in XML. ...


1. First install and download:

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

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

Now you are done with the prerequisites.


2. All targets related to internationalisation and localisation of the documentation are part of File icon.gifbuild-doc-i18n.xml. To create PO-template files, run ant -f build-doc-i18n.xml create-pot. All File icon.gifJmol*Guide.LANG.po files (which contain the translation and are maintained by the translator himself) are updated with ant -f build-doc-i18n.xml update-po. To create the final (translated) XML file File icon.gifJmol*Guide_LANG.docbook.xml, run ant -f build-doc-i18n.xml update-xml.


3. To create a translation in your language, go to doc/source/po and copy File icon.gifJmol*Guide.pot to File icon.gifJmol*Guide.LANG.po - LANG means your language code: e.g. de for German, fr for French and so on.


4. The rest is similar to the above Howto.



Translating the Jmol and FAH websites

... to write