Bulk Application Translations

Owned by Jeremy W.
Last updated: Apr 22, 2024 by Gillian Javetski
11 min read

Below are some useful tools for bulk translating applications in your CommCare application.

Using the Bulk Application Translations Tool

Overview

The bulk application translation tool allows you to manage all of the translations in your application through one Excel file. These include:

  • The name of each form and menu

  • The filepaths for form and menu icons

  • The label for cases

  • Case list and details

  • All form content, including labels, and filepaths for multimedia

Downloading the Spreadsheet

The bulk application translation relies on a structured Excel file. Click the settings icon next to the name of your application. There, you can download this file by navigating to the Bulk Application Translations file in the Language tab of your application:

Before downloading the file make sure that you have already added any languages you want to the Language List. You can change the order later if you choose to.

Download the structured file by clicking on the button shown below:

The Excel Translation File

When you open the Excel file you will see it has a number of tabs:

General Module and Form Info

The Modules_and_forms sheet allows you to specify the name of features at the menu and general form level. There is a row for each menu and a row for each form. There a couple columns pre-populated for each item:

  • Type - this is pre-populated with Form or Module. DO NOT CHANGE THIS FIELD

  • sheet_name - this specifies the location of the form or module. DO NOT CHANGE THIS FIELD

  • unique_id - DO NOT CHANGE THIS FIELD

For each form or module you can specify the following fields (for each of these there will be one additional column for each language, indicated by the language code at the end of the name):

  • default_lanuage (ex. default_en) - allows you to specify the name of the form or module in a given language.

  • label_for_cases_language (ex. label_for_cases_en) - allows you to specify the name of the case type that is shown in each module, which is relevant in case lists on the phone. THIS IS ONLY APPLICABLE TO MODULES

  • icon_filepath - allows you to specify one filepath for an image to appear in the module or form list

  • audio_filepath - allows you to specify one filepath for audio files for the module or form list

Below is an example:

Details of Module and Form Content

For each menu in the app there will be one tab (ex. module1, module2) and for each form with a unique menu, a separate tab (ex. module1_form1, module1_form2)

Module Tabs

On the module tabs you can specify translations for the case list and case details screens. The excel file will have the following fields

  • case_property - the name of the case property to be displayed in the case list or details. DO NOT CHANGE THIS FIELD

  • list_or_detail - whether the property appears in the case list or case details. DO NOT CHANGE THIS FIELD

  • default_language - there is a column for each language where you can specify the translation.

ID Mapping

If there is ID mapping in your case list or details the template will have a separate row for each option. Next to the case property will be a note about whether the line is the general text or one of the mapping values.

Graphs

If there are graphs in your case list or details the template will have a separate row for each graph title and annotation.

Form Tabs

Form tabs follow the same structure as Form Bulk Translation.

WARNING: Changing order of forms in the App Builder

If you change the order of any forms or modules in the app builder you will need to download the Excel Translation File again and start over. The file references the order of the forms and modules and the upload will fail if they no longer match.

Uploading the Translations

Once you have updated the translations you can return to the Bulk Application Translations tab and upload the file.

Upload translations before setting that language as default to avoid an error.

If you have any errors you should see a message explaining the error. After fixing the error you can try again.

In general the application builder will skip any single item that has an error and make all of the other changes, so another option is to just make any final changes in the Application Builder.

Limitations/Notes

  • The bulk application file cannot manage translations of the application name

  • If you delete any rows or tabs you will see an error message that some fields are missing; however the rest of the app will be translated without any issues.

  • Making changes to anything other than translations or media filepaths will not actually cause that change to occur in the app and could result in problems with the bulk translation tool.

Edit Bulk Translations for Forms

Overview

If your application is in more than one language, it can be easier to do all of your form translations at one time, outside of CommCare.  This is very useful if you need to send your text to someone else for translation, or if you want to add an additional language after you have already made your forms.

If you want to translate multiple forms you can use Bulk Application Translations tool.

You can use a tool called "Bulk Translation" to export all of the display text in a form, add in the translations, and then upload them all back into the form at one time.  The export can be put into an excel document so that you can send it to a translator or work on the translation separately from the form builder. Translation of buttons or error messages are not dealt with using Bulk Translations, but with Translate the CommCare User Interface.

How to Use Bulk Translation

1. In this sample application, we have two languages: English and French.  When making the application, only English text was entered. The French display text was left blank.  CommCare automatically populates the additional language display text blocks with the English text as a placeholder until the French translation is added:

2. You can click on each form and edit the local language translation for each question one by one. Or, you can use the the Bulk Translation feature to update the language for all the questions in one form at once. 

3. To use the Bulk Translations feature, click on the "Tools" box on the right side of the specific form name as demonstrated below.  The menu will open and you will see several options, including "Edit Bulk Translations" at the very bottom of the list. 

4. When you click on "Edit Bulk Translations" a box/window will appear in the center of the screen that shows all of your question text:

5. Select All the text by pressing Ctrl + A.

6. Copy the selection in the box by pressing Ctrl + C, or by right clicking and selecting "copy." 

7. Open a new Excel Spreadsheet.  Select the top left cell (Cell A1) and then Paste (Edit - > Paste, Ctrl + V, or Right Click -> Paste).  You will see all of the text from the "Edit Bulk Translations" box is now in columns in the spreadsheet:

8. Each column represents a piece of content (either text or multimedia) in each language. Some of the French versions (column B) of the text the questions are in English because we have not translated them. You can go ahead and replace the default English text with your translations.

NOTE: Not all fonts show up on all phones.  Always use UNICODE fonts where possible, and make sure to test your individual phones. See https://dimagi.atlassian.net/wiki/x/6wXKfw for more information.

  1. When you are done entering your translations, select all of the spreadsheet, and copy it (Ctrl +C).  

10. Go back to your browser with the "Edit Bulk Translations" window open.  Click in the middle of the box. Then Select All the text by pressing Ctrl + A.  If you do not place your cursor in the middle of box before pressing Ctrl+A the computer may select all of the text on the screen, including the website.   

11. Delete the contents of the window. Replace it with the newly translated text you copied in the Excel file by pressing Ctrl + V.

12. To confirm the changes, click "Update Translations."  If you press "close" the box will close and your translations will not be updated.

13. Click on one of the questions you just translated in the Question Tree, and you will now see the updated text you entered while working with the Excel file.  

14. Make sure to save your form by pressing the Green Save button at the top left corner of the screen.

15. Repeat this process for other forms in your application. 

Translating HQ: Transifex Instructions for Translators

Transifex is a very helpful bulk translation tool used by professional translators. The section below provides guidance for how to use Transifex with your CommCare application.

Click below to expand.

Create a free account in Transifex:

https://www.transifex.com/signup/

  1. Log into Transifex

  2. Search for "CommCare HQ" in Transifex's explore page.

  3. Choose a language, and hit the “Join Team” button to request access. The manager of the team needs to approve your request before you can join that team.

  4. After you have been invited approved as a translator, you’ll be notified by e-mail. From then on, you will see the project in your Dashboard.

Note: Instructions for Dimagi employees administrating transifex are on the internal wiki page.

For more detailed instructions, see Transifex's how to page.

Once you have an account:

1. In order to access the strings that have not yet been translated you will need to click on the "CommCare HQ" link on the lefthand side of your screen when you sign in. 

2. If you click on the green "translate" button at the top, it will take you to a screen that looks like this:

3. You want to click on choose a language, select the language into which you'd like to translate.

4. It will then prompt you to select which file you want to translate, there are two there, django.po and djangojs.po.  Both need to be translated, so select "All resources."

5. When you click on django po, you will see a screen that looks like this:

6. You will want to select the "untranslated" tab at the top

7. Once you have selected that tab, the terms/phrases on the left are the "strings" that we need translated.

8. Note that this document contains:

all strings on CommCareHQ.  This includes some strings that only apply to custom features and reports, and are not a core part of the website.  To avoid these, you can use the search bar at the top of the translation interface to filter strings according to the file in which they are found.  Type file:corehq/ as one filter, and file:submodules/ as another, to view only strings which are visible to all CommCare web users

In the search filter on transifex these filters will look like this:

and

How to translate template strings and code

When translating, there are some things that you must take special care to preserve (don't translate).  For instance, if a string contains the URL www.example.com, and you translate that to www.ejemplo.com, the link will fail.  If you're unsure how to translate a particular string, it's better to leave it alone and ask for clarification.  A mistake like this in translations will block us from releasing translations until it's fixed.

Strings often contain variables that will later be substituted out.  For example, the string "Case '{name}' has been closed" will turn in to "Case 'Maria' will be closed" in the English version, and "Le dossier 'Maria'  a été fermé." in the French version.

Here are some example format strings an the expected translations:

Curly braces: keep everything inside the braces.

Type {type} must be in list of domain types: {list} El Tipo {type} debe estar en un listado de tipos de dominios: {list}

Modulo interpolation: These ones can be tricky.  Here's a simple example:

Did you mean %(suggestion)s? Voulez-vous dire %(suggestion)s?

These will always start with a % sign and end in a single letter, usually s or d.  In between there can be parenthesis with a word inside, and maybe some numbers or symbols.  Be sure to include everything including the % and the letter.

%(days_remaining)03d days remaining Faltan %(days_remaining)03d días

underscore.js translations:

You may also see html in translation strings.  In general, there you should leave everything between < and > and translate things between > and <:

Running a Translation Marathon

  • Select a Translation Marathon coordinator

  • Set a goal for translation for the language project

  • Block 2 hour period that everyone on your team is available for. Nice to do this at the end of the day while everyone's wrapping up. 

  • Best to choose a week/day when most people can be together in the office. Lots of discussions bound to take place about terms

  • Buy snacks and drinks

  • Set up a playlist for music to jam along

  • On the day of:

    • Send instructions on which client everyone should bill translation time to

    • Send link to CommCare Rosetta Stone

    • Accept/Invite New Translators

    • Send reminders about specific filters to use on Transifex

    • Choose one filter to translate strings

    • Click on Untranslated String button to view only untranslated strings

    • Divide up the strings among the team so people don't over-write each others

  • Remember to SAVE all of your translations

  • Refresh often, un/click untranslated button also (sometimes it doesn't refresh correctly)

  • Keep an eye on progress! 

  • Keep it fun!

  • GO GO GO!

Tips

 

 

 

 

GENERAL

  • Be sure to reference the CommCare Rosetta Stone for some common translations

  • Error: The translation should start with an empty line. Press the "Enter" or "Return" key before the translation text.

  • Do not change anything in curly brackets {xyz }

  • If you see some untranslated text on HQ and can't find that text on transifex, it's possible it hasn't been marked for translation.  Please contact CommCareHQ support so devs can mark it for translation.

  • If first letter in the string is capital make sure your translated suggestion is also capital

  • Do not translate CommCare branded features into other languages, such as CommCare Exchange. Keep this as CommCare Exchange, pas CommCare Échange

French

  • Capitalize all major words not small articles

  • If there is an article in between such as Remplacer l'icône, you can keep the first letter a lowercase

  • Do not use infinitive form for command verbs. E.g. Télécharger should be Téléchargez