Translation Info

BabDev Shutting Down

BabDev is shutting down and its resources being discontinued. Read more in this blog post.

Using Transifex Client

One of Transifex's tools to assist developers is the Transifex client.  Although it can be a bit of a challenge to initially set up, once it is configured, it will make synchronizing your language files between your source code and Transifex a breeze.

NOTE: As of January 20, 2012, this reference has been updated for Transifex Client 0.6.1.

Setting up the Transifex Client

The first step is obviously to set up the Transifex Client on your local system.  The client is a command line based tool, so you'll be working from your Terminal window (*nix based systems) or Command Prompt (Windows).  Transifex's help page has instructions to help with that at http://help.transifex.net/features/client/index.html#getting-the-client.

Initial Configuration

Once you've set up the client, you'll need to configure each project.  You can do this in one of two ways; using the client's tx init command or you can use the generic configuration below to get started.  A huge thank you to Peter van Westen from NoNumber! for providing a full list of worldwide language codes and the language map configuration.

[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

[<project-slug>.<resource-slug>]
file_filter = path/to/<lang>/<lang>.mod_mymodule.ini
source_file = path/to/en-GB/en-GB.mod_mymodule.ini
source_lang = en_GB

Explaining the Transifex Client Project Configuration

The configuration file for each project, saved at the project's root in .tx/config, contains a [main] section with general information and at least one resource, recorded in the form of [<project-slug>.<resource-slug>]:

  • [main] section
    • host - The host site of your project files (default is https://www.transifex.net for all Transifex.net hosted projects, including Open Translators; can also optionally use https://opentranslators.transifex.net if it is defined in your Transifex Client's user configuration)
    • lang_map - A map of Transifex language codes (en_GB format) converted to what the code mapping should appear as (en-GB); this section is required for all Joomla! projects to avoid having to manually move files.  Note that the maps here are case sensitive.
    • minimum_perc - A minimum completion percentage that translations must meet in order to be downloaded; defining this param here sets the minimum_perc param for all project resources unless overridden in the resource config or when using the --minimum_perc=VALUE param when issuing the tx pull command (optional param)
    • type - The resource file type if creating new resources locally and pushing them via the client to Transifex servers; for Joomla! projects, use INI
  • Resource section
    • project-slug - The slug defined at the project edit page
    • resource-slug - The slug defined in each resource's edit page
    • file_filter - The file path where the files are stored; if a language code is used in the path, include a <lang> tag in the place of the actual code, relative to the project root
    • source_file - The file path where the source file for the resource is stored, relative to the project root
    • source_lang - The source language code of the resource as defined on Transifex
    • minimum_perc - A minimum completion percentage that translations must meet in order to be downloaded; defining this param here sets the minimum_perc param for this project resource, overrides the param in the [main] section, and is overridden by the --minimum_perc=VALUE param when issuing the tx pull command (optional param)

You will need to create a resource listing for every language file in your project.

Synchronizing Translations

It is important to keep your language files synchronized between your project and Transifex.  Here is some information on the tx push and tx pull commands.

  • tx push
    • Used to push changes to Transifex
    • Additional options for the tx push command are:
      • -h - Shows the help screen for the command
      • -l <lang> - Specify which translations you want to push (defaults to all)
      • -r <resource> - Specify the resource for which you want to push the translations (defaults to all)
      • -f - Push source files without checking modification times
      • --skip - Don't stop on errors. Useful when pushing many files concurrently.
      • -s - Push the source file to the server
      • -t - Push the translation files to the server
      • --no-interactive - Don't require user input when forcing a push
  • tx pull
    • Used to pull changes from Transifex
    • Additional options for the tx pull command are:
      • -h - Shows the help screen for the command
      • -l <lang> - Specify which translations you want to pull (defaults to all)
      • -r <resource> - Specify the resource for which you want to pull the translations (defaults to all)
      • -a - Fetch all translation files from server (even new ones)
      • -s - Force the fetching of the source file (default: False)
      • -f - Force download of translations files
      • --skip - Don't stop on errors. Useful when pushing many files concurrently.
      • --disable-overwrite - By default Transifex will fetch new translations files and replace existing ones. Use this flag if you want to disable this feature.
      • --minimum_perc=VALUE - Specify the minimum acceptable percentage of a translation in order to download it.
    • Note: If pulling a remote resource for the first time, the -l <lang> parameter (if set) must use the Transifex language (i.e. en_GB), otherwise the resource will not be downloaded.

Questions?  Comments?

Have any questions or comments?  Any additional tips to share?  Feel free to leave a comment below or make a post to the Using Transifex Client thread on the Open Translators forum.

Resources