This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Page tree
Skip to end of metadata
Go to start of metadata


The Traffic Server documentations are using reST and Sphinx, and hosted on ReadTheDocs. This documentation describes workflow of internationalization using sphinx-intl, ReadTheDocs, GitHub and Transifex.


Before start you need below tools.

  • gettext
  • sphinx
  • sphinx-intl
  • transifex-client


Below workflow is deprecated favor of to stop using ReadTheDocs. See more details in TS-4428 (May 2016)


Internationalization Workflow

Relationships between GitHub, ReadTheDocs and Transifex

Transifex doesn't have branch or version features, thus we need a project for each LTS version.


We're following Sphinx's Internationalization workflow with sphinx-int and gettext.

Update PO files

$ cd doc
$ sphinx-build -b gettext . _build/locale/pot/
$ sphinx-intl update -p _build/locale/pot/ -l <LANG>

You got a directory that contain po files. 

  •  ./locale/<LANG>/LC_MESSAGES/ 

Synchronise GitHub and Transifex

This will be done by administrators of each language periodically. 

Transifex → GitHub

  1. Pull translations from Transifex

    $ cd doc
    $ tx pull -l <LANG>
  2. Format PO files

    find . -name "*.po" -exec msgcat -w 78 -o {} {} \;
  3. Commit PO files
    $ git commit locale/<LANG>/LC_MESSAGES/<FILE>.po
  4. Push to repositories of your languages on GitHub

GitHub → Transifex

CAUTION: When you upload po files on, it will over write translations on This means translations which only on will be deleted.

  1. Pull source files from apache/trafficserver

  2. Generate POT files from rst files

    $ cd doc
    $ sphinx-build -b gettext . _build/locale/pot
  3. Update config file of tx command

    $ sphinx-intl update-txconfig-resources -p _build/locale/pot/ -d locale --transifex-project-name apache-traffic-server-<VERSION>
  4. Upload POT files

    $ tx push -s

Building the translated documentation in local

Generate mo files with translated PO files

$ cd doc
$ sphinx-intl build -d locale/ -l <LANG>

Build HTML with MO files 

$ cd doc
$ sphinx-build -b html -D language=<LANG> . _build

ReadTheDocs Theme

If you want to apply RTD theme, install sphinx_rtd_theme via pip.

Add new language

  1. Create new repositories on GitHub
  2. Create new project on ReadTheDocs
  3. Request to add new language on Transifex
  4. Request to committer or PMC on ML to add relations on ReadTheDocs
  5. Request to committer or PMC on ML to add new remap rules on

See Also

  • No labels