Transifex Client

Owned by Martin Ndegwa
Last updated: Oct 08, 2020 by Elly Kitoto
4 min read

This documentation will take you through on how to setup Transifex Client and use it to push and pull string resources.

Introduction

As you can see from this documentation https://smartregister.atlassian.net/wiki/spaces/Documentation/pages/1082654721, you can integrate transifex with GitHub - when this is properly done Transifex will make a Pull Request to the repository with the new string translations. However, there are some limitations with this approach:

  • First Transifex makes a Pull Request to the repository only when all the string translations are done.

  • Secondly Transifex can only retrieve strings from the specified GitHub branches usually master

In order to gain more control on when to push and pull strings to and from Transifex respectively it is advised to setup a Transifex client instead. The client works just like Git and will allow you to update the string resources from any branch.

Installation

If you are on a linux operating system follow the steps below. See the documentation here on How to install Transifex client on other platforms

sudo apt-get install python-pip sudo pip install transifex-client

Confirm your installation by checking the version installed

tx --version

Initialization

Transifex handles initialization like most of version control systems using tx init command. This command should be run on the root directory of your project. When you run the initialization command you will be requested to provide an API access token. Go to User Settings on your transifex account and generate a new access token. Thereafter transifex will create two configuration files.

  • ~/.transifexrc, which stores your Transifex host configuration in your home directory, or your Transifex credentials if you don’t use an environment variable for your Transifex token. You shouldn’t share this file if it contains your credentials.

  • .tx/config, which stores the mappings between your local files and Transifex in a .tx folder in your repo’s root directory. This file should be committed so it can be used by your CI tool or other developers.

The command tx init will also automatically run tx config  to help you configure the .tx/config file. If you prefer to skip this, use the --skipsetup flag.

OpenSRP Transifex Configuration Files (For Android Clients)

The tx config command allows you to update the .tx/config file that was created when you ran the tx init command. This configuration file is used to map files in a local repository/directory to resources in Transifex. Read more about file mapping here Transifex Config Mappings. You can also learn more about Transifex configurations from the documentation.

In this section we will focus on how to configure tx/config file within OpenSRP context.

  • Run tx init --skipsetup

  • Open the file .tx/config

  • Copy the content below to map Android strings.xml file to a Transifex resource. Where [project_slug.resource_slug]: Your project and resource slugs, separated by a dot. These slugs are found in your project's URL; together, they uniquely identify your resources. For example, if you have a URL such as www.transifex.com/myorganization/myproject/myresource/, the resource identifier will be myproject.myresource.

[project_slug.resource_slug] file_filter = <<app_or_library>>/src/main/res/values-<lang>/strings.xml source_file = <<app_or_library>>/src/main/res/values/strings.xml source_lang = en type = ANDROID

  • (Optional) If you are using the new Multi Language Support that store JSON form strings in a .properties file, add the following content to .tx/config file to map the property file(s) to Transifex resource(s). Replace <<property_file>> (including the angle brackets) with the name of the property file as in the Android resources directory. Repeat the same process for all the property files, each config separated by a new line.

Remember to replace <<app_or_library>> (including the angle brackets) with the name of the directory of your app or library module e.g. opensrp-app for opensrp-client-core project.

Once you have the configurations setup you can now push and pull translations to and from Transifex just like Git.

Pushing files to Transifex

When you run the tx push command, you must specify whether you’re pushing source or translation files.

To push a source file, use the -s or --source flag with the tx push command:

You MUST always include the -s flag whether you’re pushing a source file for the first time or updating an existing source file. Transifex will create new resource file if the source file is not found

To push translation files, use the -t or --translations flag with the push command:

You can also combine the two flags to push source and translation files together:

Common commands

  • -l or --language: Specify which languages you want to push translations for (defaults to all).

  • -r or --resource: Specify the resource for which you want to push the translations (defaults to all).

  • -f or --force: Push source files without checking modification times (use with precaution).

Read documentation for more command options Push: Upload files to Transifex

Pull: Download translated files from Transifex

The tx pull command lets you download translation files from Transifex for use.

To pull translations from Transifex, run the following command:

Some command options that you will find helpful

  • -a or --all : pull all translated files

  • -l or --language : specify which languages you want to pull translations for

  • -f or --force: Force the download of the translations files regardless of whether timestamps on the local computer are newer than those on the server (use with precaution).

-r or --resource: Specify the resource for which you want to pull the translations (defaults to all).

Read documentation for more command options Pull: Download files from Transifex