Quickstart: Transifex Native and Python


Transifex Native Python SDK supports versions:

  • Python 2.7
  • Python 3.5+

Install the SDK to your Python project:

$ pip install transifex-python


This section describes how to initialize the Python SDK in order to be able to retrieve translations for a given set of languages associated to a specific project.

In this process the developer should use the project token and secret, as referred in setup section.

Let's see all this in action, consider the following code block example:

from __future__ import absolute_import

from transifex.native import init, tx
# Simple case of initializing the library to be able to retrieve
# en (source language) and el, fr translations
init('project_token', ['el', 'fr', 'en'], 'project_secret')
# populate toolkit memory cache with translations from CDS service the first time
# get a translation of your project strings, the translation is served from cache
el_translation = tx.translate('my source string', 'el')
# get a translation with plurals and variable
translation = tx.translate(
            u'{cnt, plural, one {{cnt} {gender} duck} other {{cnt} {gender} ducks}}',
            params={'cnt': 1, 'gender': 'ugly'}

The translate() method can be further parameterized by the following arguments:

  • is_source boolean, False by default, to return the source string if True
  • escape boolean, True by default, to HTML, escape the translation
  • _context either a list[str] or a comma-delimited string of the context of the source string in Transifex
  • _key to define a custom string key instead of an auto-generated one based on source string and context. Amend the --verbose option of the push command so that it always prints the key of each string.

The initialization of the SDK we can be further parameterized by:

  • The missing translation policy: what translation() returns when an actual translation is missing.
  • The error policy: how translation rendering errors are handled
  • The CDS host: point to your CDS server instead of Transifex's one.
from transifex.native import init, tx

from transifex.native.rendering import PseudoTranslationPolicy, SourceStringErrorPolicy

# PseudoTranslationPolicy: on missing translation return a string that looks like the
#                          source string but contains accented characters
# SourceStringErrorPolicy: if an error happens when trying to render the translation
#                          default to the source string
init('project_token', ['el', 'fr', 'en'], ), 'project_secret',
     cds_host='',  # local dev environment CDS

Missing Policies

The available missing policies are SourceStringPolicy, PseudoTranslationPolicy, WrappedStringPolicy, ExtraLengthPolicy, ChainedPolicy.

For details please look into transifex.native.rendering package for all classes that inherit AbstractRenderingPolicy. The same package contains the available error policies. Of course you can base on these policies and extend them to cater for your needs.

Automation in Background Thread

We can further automate the fetching of translations into cache by using a background thread:

from transifex.native.daemon import daemon
# ...
# start a thread that every interval secs fetches translations in cache

Fetch new translations

When using Transifex Native, translations are served through an intermediate service called Content Delivery Service (CDS), read more about Hosting Translations. Transifex Native periodically checks and automatically fetches new translations from the CDS server, in order to force fetching all translations from the CDS you should use the following method:


Push source strings to Transifex

To send strings from your code to your Transifex project use the code displayed below:

from transifex.native.parsing import SourceString
# construct a list of strings to send
source1 = SourceString(u'Hello stranger', 
            _comment=u'A crucial comment',
            _tags=u' t1,t2 ,  t3')
source2 = SourceString(u'Hello stranger', 
            _tags=' t1,t2')
source3 = SourceString(u'{cnt, plural, one {{cnt} {gender} duck} other {{cnt} {gender} ducks}}') 
# use purge=True only if you want to delete all other Transifex strings 
# except the ones we send. Alternatively all push strings are appended
# to those existing in Tx.
response_code, response_content = tx.push_source_strings([source1, source2, source3], purge=True)

For a quick overview of Python supported Native features checkout the Transifex Native Feature Matrix.