Editing MG/Translations

Some of the existing translations are not very well maintained and, so far, only a couple languages are supported, so keeping files up to date or adding new translations helps the [[MegaGlest]] community a great deal.

==Providing translations as a volunteer==
MegaGlest's translations are managed on [http://transifex.com Transifex], a website allowing for easy software translation from within your web browser.

===Getting started===
Start by [https://www.transifex.com/signin/?next=/projects/p/megaglest/ signing up at Transifex] - that's a quick, one-time process. All accounts are free, you would only need to pay when you order an account upgrade or professional services (and you would actually have to opt-in to this, providing payment details etc.), but never as a translator. So just click on ''Sign up free''.

Once you've entered your details, click on ''I am a translator'', then head over to the [https://www.transifex.com/projects/p/megaglest/ MegaGlest project on Transifex]. Over there, just click on the language you want to translate to. On the next screen, you select which '''''resource''''' to edit - these are the various language files there are in MegaGlest. Click on a resource to get a detail screen, then just push the '''''Translate now''''' button. Only the first time you do this, you will need to review and accept the contributor license.

You can then start translating right away. On the left are the source strings, as they appear in the English language file. On the right is where you type your translation. Pretty simple, eh? There are some helpers to the left and right of each translation box. Give them a try, you will quickly find out what they are good for. Be sure to save your individual translations or, when you're done, click on the '''''Save...''''' buttons on the very bottom of the page.

By default, only those strings which are not yet translated will be shown. However, we also need you to confirm that existing translations are good so we can improve the overall quality. So once everything is translated for a language, untick the '''''Reviewed''''' box on top of the page, then verify that the previously existing translations are fine, too.

Later, when the MegaGlest developers add new translation keys, they will automatically show up on Transifex, so translation is now a continuous work. Of course, translations still matter most for releases, so we'll keep notifying you on the [https://lists.sourceforge.net/lists/listinfo/megaglest-translations translation mailing list] when it's time to get translations into shape. So be sure to subscribe, it makes [http://sourceforge.net/mailarchive/forum.php?forum_name=megaglest-translations really little traffic] .
===Adding new languages===
To add support for an entirely new language to MegaGlest, or to add a resource which is not yet available for a given language, please review our [[MG/Translations/Processing translations|translation policies]], then request the new translation on Transifex. Should you not hear back within two days, please [http://megaglest.org/contact.html contact the MegaGlest team] and state which languages we should add for you to work on. We'll add them swiftly. Please do not ask us to add a translation unless you are actually willing to start contributing to it within a few days.

==Testing your translation==
It is now very easy to test translations submitted to Transifex on your computer. All you need is to download the latest beta release (those usually come with an installer and we usually make those available some time before a stable release) or, better yet, the latest [http://megaglest.org/development.html nightly snapshot] (those come without an installer, but as two archives which you just need to unpack). If you consider yourself a developer, you could also [http://megaglest.org/development.html build MegaGlest yourself] .

Once you have installed the current development version of MegaGlest, run it, then turn to the ''Options'' menu (or you can take a look at [http://s11.postimage.org/vrmhwb0tu/megaglest_transifex_integration.jpg this screenshot] of the options menu in 3.7.0 beta2). Click the ''Advanced Translation'' button (in the top right corner). This enables some Transifex options at the bottom of the screen. Enter your Transifex '''''username''''', '''''password''''' and the [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes standard 2 character language code] for your translation. You should also be able to see this on Transifex while editing the translation: there should be a key saying ''ISO639-1'' with an English default string of ''en'' (on the left), with the translations' standard 2 character language code set on the right hand side. So, for example, if you are editing the German translation, this value would be ''de'' while for Chinese, it would be ''zh''.

Once you entered this information, click the '''''Download''''' button to pull in your work from Transifex into MegaGlest for testing. Now do test, make corrections on the Transifex website, and repeat. Now be aware that these translations apply to all installed MegaGlest versions, and older versions you may have installed (such as the latest stable release) may not work well with the new translations you downloaded from Transifex. As such, when you're done testing, you should click the ''Delete language files'' button remove the files you pulled form Transifex. This way every version of MegaGlest will revert to its own original translations that existed before your changes.

Note that the Transifex credentials you enter on the ''options'' screen will only last until you quit MegaGlest. You can also set these in [[INI|glestuser.ini]] as follows:
 TranslationGetURLUser=MyTransifexUserName
 TranslationGetURLPassword=MySecretPassword
 TranslationGetURLLanguage=de
Please be aware that '''storing your password in this file can be a security risk''', though. If you do, you must ensure that only you, not anyone else using your computer, or a different system user (apart of the administrative user), is able do read this file. On Linux, you would do so by running: chmod 600 ~/.megaglest/glestuser.ini
'''Hint:''' To switch between translations anytime while running MegaGlest, just press '''''Ctrl-L'''''. This will show a pop-up menu where you can select the new language. As you click, the change applies immediately.

==How translations work under the hood==
MegaGlest comes with several language files, a few for each supported language. These files always contain several lines which always take the same pattern:

 KeyWord=This is some lengthy translation string.

These keywords, also dubbed 'translation keys', are referenced in the source code of the game. Depending on the language the user has chosen, when these keywords are met during execution of the game, the translation string which matches this keyword is taken from the language file and printed on screen.

The main game language is English, so when a developer adds a new translation key, s/he will also edit the English language variant of the corresponding translation file and place both the translation key and the English string in there.

The English variant of the main language file is called <tt>english.lng</tt>. The latest version of <tt>english.lng</tt> is [http://megaglest.svn.sourceforge.net/viewvc/megaglest/trunk/data/glest_game/data/lang/english.lng?revision=HEAD the one in trunk]. There could theoretically be newer ones in (other) [http://megaglest.svn.sourceforge.net/viewvc/megaglest/branches/ branches] of the subversion source code repository but that's unlikely and if this should ever happen the developers should be telling you.

== Translating techtrees==
Since MegaGlest 3.8.0-dev+r4436 (that is between 3.7.1 and 3.8.0-beta1, so definitely version 3.8.0-beta1 and newer) the game fully supports (initial support was available in 3.8.0-dev+r3285) translating all the techtree related strings such as unit or structure titles and unit/attack properties which display on the graphical user interface.
===Translation of distributed techtrees===

Techtrees which are distributed and installed with MegaGlest - that's currently the ''Megapack'' only - can and should be translated by editing the [https://www.transifex.com/projects/p/megaglest/resource/megapack/ Megapack resource on Transifex] . Should there be more techtrees distributed with MegaGlest in the future, they will be added as separate resources on Transifex. Should we forget to do so, please bring it up on the translation mailing list (see below).
===Translation of non-distributed techtrees===
Normally, techtrees not distributed with MegaGlest need to be localized manually. However, a growing number of techtrees can now be translated on Transifex. 
====Translation on Transifex====

Non-distributed techtrees such as those listed on the mod menu, can now be translated on the [https://www.transifex.com/projects/p/megaglest-mods-techtrees/ megaglest-mods-techtrees project] on Transifex. Please read [[MG/Translations/Unofficial Techtree Translations|Unofficial Transifex's project of Techtree Translations]] for more information.

====Manual translation - Initialization====
Before starting with a manual translation process, please get in touch with the MegaGlest project maintainers on Transifex (they usually have [https://forum.megaglest.org/index.php?action=mlist;sa=search forum accounts] , too) or [http://megaglest.org/contact.html the MegaGlest project] itself and explain that you would like to translate a techtree (and which one). They may then grant you access to the translation project on Transifex, and this should make things considerably easier for you and other translators. 

If you would still like to manually translate, please read on. First of all, a techtree needs to be prepared for localization. This only needs to be done the first time a techtree is localized, or when units / structures / resources / upgrades have changed in the techtree's XML files.

This process creates / updates the (English) source language files containing all techtree related translation keys, based on values found in the techtrees' (already existing) XML files. To do the initialization for an example techtree ''MyTechtree'' whose main XML file is ''mytechtree.xml'', change into the directory MegaGlest is installed in and run the executable binary file as follows (again replace ''mytechtree'' by the name of your techtree):
=====Linux, OS X=====
 ./megaglest --translate-techtrees=mytechtree
=====Windows=====
 megaglest.exe --translate-techtrees=mytechtree
====Editing====

Once initialized, the techtree can be localized by manually editing the files:

* For a given techtree ''MyTechtree'' create a subdirectory named ''lang'' within the ''mytechtree'' (techtree) directory, i.e. <tt>techs/''mytechtree''/lang/</tt> - if this directory does not exist then this techtree has not been initialized for localization, yet.

* In this new directory, create a new create a new copy of the source translation file  <tt>''mytechtree''_english.lng</tt> as <tt>''mytechtree''_''language''.lng</tt> where ''language'' is the localization you wish to create (skip this step if the target file already exists). Have a look at how it's done for Megapack if you'd like to get a better idea of what the file / directory structure should look like.

* Edit the newly created file <tt>''mytechtree''_''language''.lng</tt>. You will notice that there are several keys in this format:
** <tt>ResourceTypeName_''food''=Yummies</tt>
** <tt>UnitTypeName_''archer''=Stealth Minion</tt>
** <tt>UpgradeTypeName_''advanced_architecture''=Fancy Science</tt><br />
:: Here, ''food'', ''archer'' and ''advanced_architecture'' are examples. You need to use the keywords this very techtree defines there. At runtime, the game will display any localized resource, unit, structure, upgrade, ... titles available on those localization files (make sure you have not misspelled the keys and target language / file name - check against those in Megapack). If no mathcing localizations are found or for the currently selected language there is no techtree localization, yet, the game will defaults to the source language strings.
==== Related forum discussions====
* [https://forum.megaglest.org/index.php?topic=8845 Support for 100% translation]
* [https://forum.megaglest.org/index.php?topic=8292 Translatable techtrees]

== Keep yourself in the loop==
Translations are never complete: During development it will happen that new translation keys are added, and old ones removed, so it is very likely that changes need to be made to existing translations to make them complete for the next release.

So if you're already helping with translations (or just consider doing so), please make sure you also subscribe to [https://lists.sourceforge.net/lists/listinfo/megaglest-translations the megaglest-translations mailing list]. This mailing list is used to notify translators before we will release a new version, so they have a chance to update and complete translations for the upcoming release.

==See Also==
*[[MegaGlest]]
*[[MG/FAQ|Frequently Asked Questions]]
*[[MG/Translations maintenance|Translations maintenance]]
*[[Scenarios]]
[[Category:MG]]