After 3 days of fight with Transifex my ordeal seems to be over! First a big thank you to Ratnadeep Debnath from transifex for working with me and fixing those bugs... And a big thank you for Peter van Westen for helping with my baby steps.
This tutorial is for Joomla developers that are considering the switch to transifex to manage their extension translations. Read on and I think that you will be up and running in no time.
Ok, let us first look at my joomla setup. Each of my extensions follow the joomla file structure. Look at the screenshot:
My language files are stored in the following way
language/
administrator/language/
So, now that we know how I keep my language files let us go to transifex and create our project. On your dashboard click the "new project" button.
now on the next screen don't input an url to your project on github or assembla, but click the "fill them up manually" button.
Now feel up the form:
For tags don't forget to choose opentranslators(if you are going to work with them of course). If you want to input an url to your website, or to some page with instructions for translators - click the "view advanced fields". Once you are ready click "save project"
All right! Now you should see a screen similar to this one:
Ok, we are nearly half there! The next step is to download the client. It is a little bit difficult to find it on their website, so here is the link to both the documentation and links to the download for windows. (http://help.transifex.net/features/client/index.html#user-client-06-whats-new )
If you look at the screenshot with my extension structure again you should see that I have a tx.exe file (the transifix client) + a .tx folder there. This folder was created from the tx.exe. So you basically need to start your console. You need to navigate to your extension directory and once you are there, type:
tx.exe init
The init command will create the .tx folder for you and it will place a .config file (of course once you type tx.exe init - you need to follow the instructions on the screen).
Now for our joomla extension we need to change the default .config file. ( you know the procedure - right click on the file - open with -> choose your preferred editor) . Change the content of the file with this:
[main]
host = https://www.transifex.net
lang_map = af_ZA: af-ZA, am_ET: am-ET, ar_AE: ar-AE, ar_BH: ar-BH, ar_DZ: ar-DZ, ar_EG: ar-EG, ar_IQ: ar-IQ, ar_JO: ar-JO, ar_KW: ar-KW, ar_LB: ar-LB, ar_LY: ar-LY, ar_MA: ar-MA, ar_OM: ar-OM, ar_QA: ar-QA, ar_SA: ar-SA, ar_SY: ar-SY, ar_TN: ar-TN, ar_YE: ar-YE, arn_CL: arn-CL, as_IN: as-IN, az_AZ: az-AZ, ba_RU: ba-RU, be_BY: be-BY, bg_BG: bg-BG, bn_BD: bn-BD, bn_IN: bn-IN, bo_CN: bo-CN, br_FR: br-FR, bs_BA: bs-BA, ca_ES: ca-ES, co_FR: co-FR, cs_CZ: cs-CZ, cy_GB: cy-GB, da_DK: da-DK, de_AT: de-AT, de_CH: de-CH, de_DE: de-DE, de_LI: de-LI, de_LU: de-LU, dsb_DE: dsb-DE, dv_MV: dv-MV, el_GR: el-GR, en_AU: en-AU, en_BZ: en-BZ, en_CA: en-CA, en_GB: en-GB, en_IE: en-IE, en_IN: en-IN, en_JM: en-JM, en_MY: en-MY, en_NZ: en-NZ, en_PH: en-PH, en_SG: en-SG, en_TT: en-TT, en_US: en-US, en_ZA: en-ZA, en_ZW: en-ZW, es_AR: es-AR, es_BO: es-BO, es_CL: es-CL, es_CO: es-CO, es_CR: es-CR, es_DO: es-DO, es_EC: es-EC, es_ES: es-ES, es_GT: es-GT, es_HN: es-HN, es_MX: es-MX, es_NI: es-NI, es_PA: es-PA, es_PE: es-PE, es_PR: es-PR, es_PY: es-PY, es_SV: es-SV, es_US: es-US, es_UY: es-UY, es_VE: es-VE, et_EE: et-EE, eu_ES: eu-ES, fa_IR: fa-IR, fi_FI: fi-FI, fil_PH: fil-PH, fo_FO: fo-FO, fr_BE: fr-BE, fr_CA: fr-CA, fr_CH: fr-CH, fr_FR: fr-FR, fr_LU: fr-LU, fr_MC: fr-MC, fy_NL: fy-NL, ga_IE: ga-IE, gd_GB: gd-GB, gl_ES: gl-ES, gsw_FR: gsw-FR, gu_IN: gu-IN, ha_NG: ha-NG, he_IL: he-IL, hi_IN: hi-IN, hr_BA: hr-BA, hr_HR: hr-HR, hsb_DE: hsb-DE, hu_HU: hu-HU, hy_AM: hy-AM, id_ID: id-ID, ig_NG: ig-NG, ii_CN: ii-CN, is_IS: is-IS, it_CH: it-CH, it_IT: it-IT, iu_CA: iu-CA, ja_JP: ja-JP, ka_GE: ka-GE, kk_KZ: kk-KZ, kl_GL: kl-GL, km_KH: km-KH, kn_IN: kn-IN, ko_KR: ko-KR, kok_IN: kok-IN, ky_KG: ky-KG, lb_LU: lb-LU, lo_LA: lo-LA, lt_LT: lt-LT, lv_LV: lv-LV, mi_NZ: mi-NZ, mk_MK: mk-MK, ml_IN: ml-IN, mn_CN: mn-CN, mn_MN: mn-MN, moh_CA: moh-CA, mr_IN: mr-IN, ms_BN: ms-BN, ms_MY: ms-MY, mt_MT: mt-MT, nb_NO: nb-NO, ne_NP: ne-NP, nl_BE: nl-BE, nl_NL: nl-NL, nn_NO: nn-NO, nso_ZA: nso-ZA, oc_FR: oc-FR, or_IN: or-IN, pa_IN: pa-IN, pl_PL: pl-PL, prs_AF: prs-AF, ps_AF: ps-AF, pt_BR: pt-BR, pt_PT: pt-PT, qut_GT: qut-GT, quz_BO: quz-BO, quz_EC: quz-EC, quz_PE: quz-PE, rm_CH: rm-CH, ro_RO: ro-RO, ru_RU: ru-RU, rw_RW: rw-RW, sa_IN: sa-IN, sah_RU: sah-RU, se_FI: se-FI, se_NO: se-NO, se_SE: se-SE, si_LK: si-LK, sk_SK: sk-SK, sl_SI: sl-SI, sma_NO: sma-NO, sma_SE: sma-SE, smj_NO: smj-NO, smj_SE: smj-SE, smn_FI: smn-FI, sms_FI: sms-FI, sq_AL: sq-AL, sr_BA: sr-BA, sr_CS: sr-CS, sr_ME: sr-ME, sr_RS: sr-RS, sv_FI: sv-FI, sv_SE: sv-SE, sw_KE: sw-KE, syr_SY: syr-SY, ta_IN: ta-IN, te_IN: te-IN, tg_TJ: tg-TJ, th_TH: th-TH, tk_TM: tk-TM, tn_ZA: tn-ZA, tr_TR: tr-TR, tt_RU: tt-RU, tzm_DZ: tzm-DZ, ug_CN: ug-CN, uk_UA: uk-UA, ur_PK: ur-PK, uz_UZ: uz-UZ, vi_VN: vi-VN, wo_SN: wo-SN, xh_ZA: xh-ZA, yo_NG: yo-NG, zh_CN: zh-CN, zh_HK: zh-HK, zh_MO: zh-MO, zh_SG: zh-SG, zh_TW: zh-TW, zu_ZA: zu-ZA
type = INI
[compojoom-hotspots.admin_com_hotspots]
file_filter = administrator\language\\ .com_hotspots.ini
source_file = administrator\language\en-GB\en-GB.com_hotspots.ini
source_lang = en_GB
minimum_perc = 100
[compojoom-hotspots.frontend_com_hotspots]
file_filter = language\\ .com_hotspots.ini
source_file = language\en-GB\en-GB.com_hotspots.ini
source_lang = en_GB
minimum_perc = 100
So, as you can see - this is the .config file for the Hotspots extension. Let us look at the [main] part of the file.
We have a host declaration, then we have a lang_map . You can read more about the lang_map here: http://opentranslators.org/br/forum/topic/69-developers-mapping-xxxx-to-xx-xx-syntax
The type is really important - it is used from transifex to determine what kind of translations you have (without this you won't be able to automatically create a resource)
The next part is the [compojoom-hotspots.admin_com_hotspots] resource. The compojoom-hotspots string is the project slug and the admin_com_hotspots part is the resource name. Here is a link to the Hotspots project on transifex: https://www.transifex.net/projects/p/compojoom-hotspots/ - you see - we have compojoom-hotspots in the url (this is your project slug) and if you look at the page in the resources part we have admin_com_hotspots.
The file filter is basically your way of telling the transifex client how your files are stored. In our case administrator\language\
The source file is the link to your source - the file that will be used to translate from.
The minimum_perc variable tells the transifex client that it needs to pull files from the server that are only 100 percent complete. You can write any number from 0 to 100 there - it is your choice if you want to include incomplete translations with your extension or not.
Now I think that you are getting the idea! You need to modify the above config file to match your project. Once you are ready, then go again to the console and push those source files to the transifex server:
As you can see transifex found out that the admin_com_hotspots and frotnend_com_hotspots resources were not exisitng and it created them. (you don't need to create your resources manually one by one trough the web interface - a proper config file does this automatically for you)
The next step would be to push your available translations(if you have any):
That was it! Now your source files should be on transifex together with your translations. Now you can contact opentranslators.org and let them do their magic!
Few things should be noted!
- If your language files are for joomla 1.6 then make sure that the first string in each file is semi-column like ; - this will ensure that transifex will treat your language files for joomla 1.6/1.7/2.5+ . Otherwise you will get invalid files when you do tx.exe pull
- If you have errors in your language files, then they won't be uploaded to transifex! It took me some time to realize this, but transifex ignores those files and doesn't warn you about them right now. (Ratnadeep from transifex is promising that they will fix this!)
Here we are at the end of this tutorial! I hope that it helped you to save time, a lot of time! If you have any questions or suggestions use the form below and let us together improve this tutorial!