View source for Translate the GUI into another language

[[Category:Languages]]
[[Category:Tutorials]]


=Selecting the language for an Orbiter=
To select the Language for an Orbiter, use [[LinuxMCE Admin Website]]-->Wizard-->Devices-->Orbiter.

=How to translate=
Note: this howto is made for LinuxMCE 0810. Other versions may require changes in specific steps.

LinuxMCE uses a smart system for translating GUI text elements. All text bits are stored in the main database as well as the translations. The text elements are picked up when generating orbiter screens. LinuxMCE selects the text elements corresponding to the language setting of the orbiter and whenever a piece of the GUI is not translated yet, it does a fallback to the English text.

To perform a translation always follow these steps:
# update your database (sqlCVS update)
# create your language if it does not exist yet
# do the translation (or parts of it)
# commit your database changes (sqlCVS commit)

Basically there are two different ways to perform the translation - you can directly work with the database or you can use Designer as a desktop application.

==Working with the database==

===Preparation===

To have UTF8 text data in the database following steps should be done:
* default charset for server should be set to utf8 in the /etc/mysql/my.cnf:
 [mysqld]
 init_connect='SET NAMES utf8; SET collation_connection = utf8_general_ci;'
 default-character-set=utf8                                                
 character-set-server=utf8                                                 
 collation-server=utf8_general_ci                                          
 skip-character-set-client-handshake  
* default charset for client should be set to utf8 in the /etc/mysql/my.cnf:
 [client] 
 default-character-set=utf8
* default charset for desired database should be set to utf8:
 alter database pluto_main charset=utf8;
* default charset for desire table should be set to utf8:
 alter table Text_LS charset=utf8;
* default charset for all text fields in the table should be also set to utf8:
 alter table Text_LS modify column `Description` longtext CHARACTER SET utf8 COLLATE utf8_general_ci
* the client - PHP or Perl script, C++ libs etc should tell mysql that connection is in utf8. Here is an example for Perl:
 my $dbh = DBI->connect("dbi:mysql:pluto_main;host=localhost", "root") or die "Cannot connect to database: $DBI::err!";
 $dbh->{'mysql_enable_utf8'} = 1;
 $dbh->do('SET NAMES utf8');

For C++ right after calling mysql_init() but before mysql_connect() or mysql_real_connect() using function [http://dev.mysql.com/doc/refman/5.0/en/mysql-options.html mysql_options()] we can set UTF8 charset for connection:
 mysql_options(&mysql, MYSQL_SET_CHARSET_NAME, 'utf8');

and run the SQL statement right after connection will be done:
 mysql_options(&mysql,MYSQL_INIT_COMMAND, 'SET NAMES utf8');

===Translation===

As stated above, all text elements are stored in the main database (pluto_main). The tables of particular interest are "[[Database.pluto_main.Text|Text]]", "[[Database.pluto_main.Text_LS|Text_LS]]" and "[[Database.pluto_main.Language|Language]]". 
: "Text" : Contains all text elements that are used by the GUI. The single text elements are identified by the field PK_Text
: "Language" : Defines the available languages for the GUI. The single languages consist of an identifier PK_Language and a descriptive string, e.g, "English", "German", "French"
: "Text_LS" : Contains the translated text elements which are linked to "Text" and "Language" tables via the foreign keys FK_Language and FK_Text

To work with the database you can use several programs, e.g., mysql command line client, phpmyadmin web frontend, mysql browser desktop application... I will not go into details how to work with databases here.

When creating or modifying rows of the tables make sure to never touch the fields called psc_<something>. These are part of the sqlCVS system and are handled by sqlCVS upon checkin/update etc. If you leave these fields alone MySQL inserts the default values which are just fine.

Never (!) update/overwrite an existing row when creating a new translation. Only change existing rows when you make a correction to an already existing translation.

===Update database=== 

The database should be updated before starting any work on it. You can easily do this in web admin. Go to ''Advanced->sqlCVS->Update''. Leave the configuration fields with the default values
 sqlCVS Host: schema.linuxmce.org
 Port:        3999
 Username:    anonymous
 Password:    nopass
 Database:    pluto_main
Scroll down and click on ''Designer->Select All'' and than hit the ''Next'' button. Wait until the process is finished (wait until "Status: success" appears in the pop-up window.

More details on sqlCVS usage can be found [[SqlCVS|here]].

===Create a new language definition===
If you would like to do a translation to a currently unsupported language you first have to create a definition for that language. To do this, create a new row in pluto_main.Language with the name of the language and remember the ID PK_Language.

''I suggest to use the native spelling of the language name and not the English term, e.g. use "Deutsch" instead of "German" or "Française" instead of "French" to make the selection more user friendly. [[User:Chriss|chriss]] 11:36, 7 July 2009 (CEST)
''

===Translating===
For every term that needs to be translated (remember, there is a smart fallback system, e.g., you do not need to translate the letters for the on-screen keyboard ;)) create a new row in pluto_main.Text_LS where FK_Language has to contain the ID of your language and FK_Text has to contain the ID of the translated row from pluto_main.Text. Best way for translating is to iterate through all entries in pluto_main.Text and create the translation.

===Check in translation===
You can use web admin again to check in your work. Go to ''Advanced->sqlCVS->CheckIn''. The configuration should be the same as above. Scroll down and tick the check box at ''Designer'' and under Designer you also need to tick the check boxes at ''Language'' and ''Text_LS''. Finally enter a comment to describe what you are checking in and hit ''Next''. Watch the progress in the pop-up window.

After successfully translating the GUI and checking in all changes please create a ticket in [http://svn.linuxmce.org/ Trac], make it a feature_patch, name it "translation to <yourlanguage>" and give all the sqlCVS batch numbers in the description to have a developer approve the changes to the database.

==Working with Designer==
[[Designer]] is a software to modify the GUI of LinuxMCE. It can also be used to create new text element and the corresponding translations. Check the linked page and the wiki on how to get hold of Designer and how to make it start up.

The process of updating your database before editing and committing your changes after editing are the same as described above.

''Note: IMHO there currently is no option to define new languages in HADesigner [[User:Chriss|chriss]] 22:26, 7 July 2009 (CEST)''

Designer has a comfortable interface for changing and translating text elements. First select the text tab on the DesignObj Browser:
[[Image:Designer_obj_browser.png]]

Find the items to translate in the categories and double-click on the element to open up the editor window. The editor window will expand if there are more languages defined.
[[Image:Designer_edit_text.png]]

=For developers=
The text which you see on the Orbiter is stored in the LinuxMCE_main database in the "Text" and "Text_LS" tables.  Each block of text or phrase has an entry in the text table. The Text_LS table has text in the language specified.

To add a new language you need to add a new record to the Language table, and then add new records to Text_LS, with the translated version of each text blocked.  It is easiest to do this in the [[Designer]] program.  Designer will show you all the text blocks logically laid out in folders and categories.  It is not necessary to translate the entire user interface all at once.  You can translate only certain phrases and when [[Orbiter Generator|OrbiterGen]] rebuilds the User Interface it will use English for any phrases that are not translated.