= User Guidelines Localisation =
[[TOC]]
== Contributing to the Translations of Sahana Eden ==
Translation to other languages is highly appreciated.

It would also be great to have someone volunteer to be our Translations lead / coordinator.

== Web2Py Localisation System ==
Sahana Eden is built using Web2Py & as-such it inherits the Web2Py localisation architecture:
* http://www.web2py.com/books/default/chapter/29/04/the-core#Internationalization--and-Pluralization-with-T

NB Currently Sahana is NOT using the pluralisation functionality (help migrating to that would be appreciated!)

Current languages translated to some extent:
* https://github.com/flavour/eden/tree/master/languages

== Translation Tools ==
=== Sahana Translation Interface ===
We have built our own Translation module which allows you to export the *relevant* strings to an .xls file, a .po file or upload to Pootle:
* http://127.0.0.1:8000/eden/admin/translate

It also supports uploading updated [partial] files to be merged with the existing {{{languages/code.py}}}

If the language you want isn't yet available, then create a new file using the [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ISO 639-1 Code] of the Language as the filename. If it is a national variation of a language, eg. New Zealand English, add a suffix to the filename: "en_nz.py".

=== Pootle ===
We maintain a [http://pootle.sahanafoundation.org Pootle Server] as a collaborative space to both do the initial translations and also to allow people to suggest improvements.

Please see the [UserGuidelinesLocalisationPootle Pootle User Guidelines] for instructions or contact the MailingList for advice.

Convert to a .po file for use in Pootle (or other PO file tools such as [http://translate.sourceforge.net/wiki/virtaal/index Virtaal]):
 * "web2py2po" scripts (part of the [http://translate.sourceforge.net/wiki/toolkit/py2web2po "Translate Toolkit"])
  * Use 1.8.1 (https://github.com/translate/translate/archive/1.8.1.tar.gz) or this [http://eden.sahanafoundation.org/attachment/wiki/UserGuidelines/Localisation/web2py2po.diff patch] for 1.8.0
  * 1.10+ have UTF-8 issues (po2web2py needs updating to match rest of system)

For UTF-8, beware of the encoding - needs to be 'without BOM' or 'ANSI as UTF-8'.[[BR]]
- this is both within the {{{languages/}}} file & also with any UTF-8 direct in customised Views.[[BR]]

{{{
web2py2po -i zh-tw.py -o zh-tw.po

# Use Pootle &/or Virtaal to translate, then:

po2web2py -i zh-tw.po -o zh-tw.py
}}}

NB The .py output looks wrong, with raw UTF-8 binary characters, however it works fine if you let Web2Py process it:
 * copy into 'languages' folder
 * Add this to {{{models/000_config.py}}}: {{{settings.L10n.languages_readonly = False}}}
 * run Eden with this language: http://127.0.0.1:8000/eden/default/index?_language=xx
 * comment the setting in {{{models/000_config.py}}}

See SysAdmin/Pootle

=== Transifex ===
At one time we started to try out [https://www.transifex.com/organization/sahana Transifex] to do the same job as Pootle, so if you prefer to use that then we can support you there too.

=== Zanata ===
Zanata is being tried for Brazilian Portuguese here:
* https://translate.zanata.org/iteration/view/sahana_eden_brumadinho/sahara_eden?dswid=-4558
=== Web2Py Admin UI  ===
You can edit the language file directly in the Web2Py Admin UI.

If wishing to provide access to just language strings & not the rest of the source code:
 * http://www.web2py.com/appliances/default/show/9

* Script to update language files:
{{{ 
cd web2py
python web2py.py -S eden -R applications/eden/static/scripts/tools/languages.py
}}}

=== Using Auto-Translator ===
You can -also- try a beta tool, which translates any file (including the web2py languages files) using the Google Translate API:
 * Go to [http://pypi.python.org/pypi/auto-translator/ "Auto-Translator"], download, uncompress the .tar.gz archive
 * Inside the uncompressed directory, execute the application with:
   - ./autotranslate.py (parameters)
   or
   - python autotranslate.py (parameters)

   (The parameters are: '''filename, origin language and destination language''')[[BR]]
   Example: ./autotranslate.py /home/johndoe/web2py/applications/eden/languages/es.py en es [[BR]]
   Wait (you'll see an advance status) and DONE.  Just refine the translations (inside web2py or just open with a text editor)[[BR]]
   [[BR]]
   Please provide any bug report or problem to the main list

== Spreadsheet Tips ==
To remove rows where source & target are the same, can create a new column with =IF(A2=B2;1;0), Paste Special, Sort & Delete 1s 

* http://stackoverflow.com/questions/6002256/is-it-possible-to-force-excel-recognize-utf-8-csv-files-automatically 
 1. Save the exported file as a csv
 1. Open Excel
 1. Import the data using Data-->Import External Data --> Import Data
 1. Select the file type of "csv" and browse to your file
 1. In the import wizard change the File_Origin to "65001 UTF" (or choose correct language character identifier)
 1. Change the Delimiter to comma
 1. Select where to import to and Finish

== Translate Wiki Pages ==
* Translated pages with [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ISO 639-2 Language Code] extension (original english page = no extension), e.g.
 * '''original page:''' eden.sahanafoundation.org/wiki/BluePrintInternationalisation
 * '''german translation:''' eden.sahanafoundation.org/wiki/BluePrintInternationalisation'''/de'''

* Insert ![[TranslatedPages]] macro to display a list of available translations of a page (at best at bottom of page)

== See Also ==
* DeveloperGuidelines/Internationalisation
* BluePrint/Internationalisation