Translate the HOT Tasking Manager into Your Language

HOT Tasking Manager currently supports 26 languages, making it accessible to humanitarian mappers and project managers in communities around the world. Translations are managed through Transifex, a collaborative localisation platform that requires no programming knowledge to use. Whether you are a fluent speaker wanting to improve a translation or a developer maintaining locale files, this guide covers everything you need.

Supported Languages

The following languages ship with Tasking Manager by default. The codes correspond to locale files stored under frontend/src/locales/.

ar       عربى               (Arabic)
cs       Čeština            (Czech)
de       Deutsch            (German)
el       Ελληνικά           (Greek)
en       English            (English — source language)
es       Español            (Spanish)
fa_IR    فارسی              (Persian)
fr       Français           (French)
he       עברית              (Hebrew)
hu       Magyar             (Hungarian)
id       Indonesia          (Indonesian)
it       Italiano           (Italian)
ja       日本語              (Japanese)
ko       한국어              (Korean)
mg       Malagasy           (Malagasy)
ml       Malayalam          (Malayalam)
nl_NL    Nederlands         (Dutch)
pt       Português          (Portuguese)
pt_BR    Português (Brasil) (Brazilian Portuguese)
ru       Русский язык       (Russian)
sv       Svenska            (Swedish)
sw       Kiswahili          (Swahili)
tl       Filipino (Tagalog) (Filipino)
tr       Türkçe             (Turkish)
uk       Українська         (Ukrainian)
zh_TW    繁體中文            (Traditional Chinese)

Contributing a Translation

Create a Transifex account

Visit transifex.com and sign up for a free account. No coding experience is required.

Join the hotosm-translator team

Navigate to the Tasking Manager Transifex project and apply to join the hotosm-translator team. Everybody is welcome — approval is typically fast.

Select your language and start translating

Once accepted, choose your language from the project dashboard. You will see a list of resource files. The primary resource is the English source (en.json). Translate strings directly in the Transifex editor — you can work on as many or as few strings as you like, and your changes are saved automatically.

Review existing translations

Even if a language is already partially translated, community review is invaluable. Look for strings marked as unreviewed or that appear machine-translated, and suggest improvements using Transifex’s review workflow.

Translators receive an automatic notification every time the HOT development team pushes new source strings to Transifex. Keep an eye on your Transifex notifications to stay up to date with strings that need translating.

Developer Workflow

For developers working on the frontend codebase, the translation pipeline involves exporting new strings from the source code, pushing them to Transifex, and pulling completed translations back before releases.

Export New Translatable Strings

Whenever you add or modify user-facing strings in the frontend, regenerate the source locale file so translators can see the new content:

cd frontend
yarn build-locales

This command scans all messages.js files in the frontend source and writes updated key/value pairs to frontend/src/locales/en.json. Include this file in your commit and Pull Request.

Run yarn build-locales before every PR that touches translatable strings. It keeps the source file in sync and prevents translators from working against a stale source.

Setting Up the Transifex CLI

Pushing and pulling translations programmatically requires the Transifex CLI and a Transifex API key. Initialise the CLI from the project root:

tx init

The init wizard will prompt for the service URL (accept the default) and your Transifex credentials. Configuration is stored in .tx/config, which maps local locale files to Transifex resources.

Running the Transifex CLI

Option 1: Docker-based CLI (Recommended)

Use the provided helper scripts to run the CLI inside a Docker container — no local installation required:macOS / Linux:

# Download the latest translations from Transifex
./scripts/transifex/tx-docker.sh pull

# Push updated source strings (English) to Transifex
./scripts/transifex/tx-docker.sh push -s

Windows (PowerShell):

# Download the latest translations from Transifex
./scripts/transifex/tx-docker.ps1 pull

# Push updated source strings (English) to Transifex
./scripts/transifex/tx-docker.ps1 push -s

The scripts mount your project directory into the container and handle system certificates for secure API communication. If you encounter certificate-related errors, update the certificate paths in the script or switch to the native CLI method.

Option 2: Native CLI install

macOS / Linux:

curl -sSL https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash

Windows: Download the binary from the Transifex CLI Releases page.Once installed, use the CLI directly:

tx pull   # Pull all translations from Transifex
tx push   # Push source strings to Transifex

Key arguments:

Argument	Effect
`-s`	Push/pull source files only (English)
`-t`	Push/pull all translation files
`-af --mode translator`	Pull all languages in translator mode (used before releases)

Push New Source Strings

After a PR with new translatable strings is merged to develop, push the updated English source to Transifex so translators are notified:

# Docker method
./scripts/transifex/tx-docker.sh push -s

# Native CLI method
tx push -s

Pull Latest Translations (Before a Release)

Before cutting a major release, pull all available translations from Transifex into the locale directory:

# Docker method
./scripts/transifex/tx-docker.sh pull

# Native CLI method
tx pull -af --mode translator

This command downloads all language files into frontend/src/locales/. Check the Transifex dashboard to review translation completion rates per language before deciding which locales to bundle.

Restricting Available Languages

If you are running your own Tasking Manager instance and want to offer only a subset of languages, set the following environment variables in your deployment configuration:

TM_SUPPORTED_LANGUAGES_CODES="en, fr, es, de"
TM_SUPPORTED_LANGUAGES="English, Français, Español, Deutsch"

TM_SUPPORTED_LANGUAGES_CODES and TM_SUPPORTED_LANGUAGES must always contain exactly the same number of entries. A mismatch will cause the language selector to display incorrectly.

Adding a New Language

Add the language on Transifex

Open the Tasking Manager Transifex dashboard and add the new language to the project.

Update the Transifex config file

Edit .tx/config and add a mapping for the new locale file:

[tasking-manager.version-4]
trans.ml = frontend/src/locales/ml.json

Replace ml with the appropriate BCP-47 language code for your language.

Add the language to the backend configuration

Open backend/config.py and add the language code and display name to the SUPPORTED_LANGUAGES dictionary:

SUPPORTED_LANGUAGES: dict = {
    "codes": os.getenv(
        "TM_SUPPORTED_LANGUAGES_CODES",
        ", ".join([
            # ... existing codes ...
            "ml",   # ← add the new code here
        ]),
    ),
    "languages": os.getenv(
        "TM_SUPPORTED_LANGUAGES",
        ", ".join([
            # ... existing names ...
            "Malayalam",  # ← add the display name here (same position)
        ]),
    ),
}

Update the frontend internationalisation files

Add the new locale to frontend/src/utils/internationalization.js by appending it to the supportedLocales array, and add any required polyfills in frontend/src/utils/polyfill.js.

Handle iso-countries-languages (if needed)

If the new language is not yet supported by the iso-countries-languages package used by Tasking Manager, update that library and publish a new version before completing the integration.

Pull and commit the locale file

Pull the locale file from Transifex to create the JSON file locally, then commit everything together:

tx pull -l LANGUAGE_CODE
git add .tx/config frontend/src/locales/LANGUAGE_CODE.json backend/config.py \
        frontend/src/utils/internationalization.js frontend/src/utils/polyfill.js
git commit -m "Add LANGUAGE_NAME (LANGUAGE_CODE) language support"

Get Started

Core Concepts

Deployment & Operations

Contributing

Translate the HOT Tasking Manager into Your Language

Supported Languages

Contributing a Translation

Developer Workflow

Export New Translatable Strings

Setting Up the Transifex CLI

Running the Transifex CLI

Push New Source Strings

Pull Latest Translations (Before a Release)

Restricting Available Languages

Adding a New Language

Helpful Links

Build docs developers (and LLMs) love

Get Started

Core Concepts

Deployment & Operations

Contributing

Documentation Index

​Supported Languages

​Contributing a Translation

​Developer Workflow

​Export New Translatable Strings

​Setting Up the Transifex CLI

​Running the Transifex CLI

​Push New Source Strings

​Pull Latest Translations (Before a Release)

​Restricting Available Languages

​Adding a New Language

​Helpful Links

Build docs developers (and LLMs) love

Supported Languages

Contributing a Translation

Developer Workflow

Export New Translatable Strings

Setting Up the Transifex CLI

Running the Transifex CLI

Push New Source Strings

Pull Latest Translations (Before a Release)

Restricting Available Languages

Adding a New Language

Helpful Links