This documentation will take you through on how to setup Transifex Client and use it to push and pull string resources.
As you can see from this documentation Transifex: Adding GitHub Repositories, 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.
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 |
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.
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.
[project_slug.resource_slug] file_filter = <<app_or_library>>/src/main/resources/<<property_file>>_<lang>.properties source_file = <<app_or_library>>/src/main/resources/<<property_file>>.properties source_lang = en |
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.
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:
tx push -s |
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:
tx push -t |
You can also combine the two flags to push source and translation files together:
tx push -s -t |
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
The tx pull command lets you download translation files from Transifex for use.
To pull translations from Transifex, run the following command:
tx pull -a |
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