Internationalization: Coding

Introduction

Internationalization is the process of designing a software application so that it can potentially be adapted to various languages and regions without engineering changes.

-- Wikipedia

KA Lite is a cross-cultural tool and internationalization of the app by translating strings is a key component to making this content accessible anywhere.

We use an automated, Django-based tool for finding and extracting translatable strings. This means that devs, when we are coding, are responsible to mark up the code in standard ways, in order to allow this program to find the translatable strings.

Below, we've linked to tutorials for how to use Django's built-in internationalization features when writing code for KA Lite.

How to wrap strings in Django:

1. templates

2. view code

3. Javascript. We import the JavaScript translation dictionary into our base template, so no need to worry about importing. In your js code, simple wrap strings in a gettext function like the following example: document.write(gettext('this is to be translated'));

4. Handlebars templates must use the {{_ "hello world" }} helper function. Use literal strings because variables cannot be picked-up by the makemessages management command for i18n. TODO(cpauya): This is still being tested manually if translations does happen for handlebars templates.

i18n on OSX

1. locale.getlocale() problems on OSX

How to manually check translations.

References:

• Central == the server hosted at http://staging.learningequality.org/ with repository at https://github.com/fle-internal/ka-lite-central
• Distributed == the KA-Lite server at https://github.com/learningequality/ka-lite/
• Version == 0.13.0, this is hardcoded in version.py at the kalite folder of the project's repository
• Crowdin KA-Lite site == https://crowdin.com/project/ka-lite/en

Requirements:

• Central must be running at http://127.0.0.1:8000/ based on master branch

  • local_settings.py must have these entries:

     DEBUG = True
     CROWDIN_PROJECT_ID = "ka-lite"
     CROWDIN_PROJECT_KEY = "<project-key-here>"

  • an alternative is to get a copy of the kalite-en.zip and save it to /_crowdin_cache/kalite-en.zip

  • follow the doc on local_settings.py setup

  • the *CROWDIN_PROJECT_* keys are private; you'll have to get in touch with a (FLE) team member who has them.

• Distributed must be running at http://127.0.0.1:8008/ based on develop branch and must be pointing to central server running locally

Steps to manually verify translations

For this example, we will translate the "Facility" text because it is used both at the Django and Handlebars templates.

1. At the central server, run python manage.py update_language_packs --no-srts --no-dubbed -l en which will save to /_crowdin_cache/kalite-en.zip and generate the language pack.
2. Extract the kalite-en.zip.
3. Edit kalite-en/versioned/0.13-djangojs.po.
   1. Add msgid "Facility" if it doesn't exist. Add/edit it's msgstr "Facility--djangojs.po--0.13" then save 0.13-djangojs.po.
   2. Save and close.
4. Edit kalite-en/versioned/0.13-django.po.
   1. Add msgid "Facility" if it doesn't exist. Add/edit it's msgstr "Facility--django.po--0.13" then save 0.13-django.po.
   2. Save and close.
5. compress your edits back to /_crowdin_cache/kalite-en.zip, overwrite it if needed
6. Re-run python manage.py update_language_packs --no-srts --no-dubbed -l en to re-generate the /centralserver/language_packs/0.13/en.zip file.
7. Note: The 0.13/en.zip file is now served by the Central server, so the Distributed server can download it now.
8. At the distributed server, call python manage.py languagepackdownload -l en --commandline.
9. Restart the distributed server to load the language pack.
10. Visit the Coach Reports page and check that the "Facility" entry of the facility dropdown is translated.

This means that the {{_ "Facility" }} handlebars helper function did not use the i18n key and was not able to translate the "Facility" text. Or perhaps I'm missing something.

You may use any other texts like "Add a new Facility" as long as it is used both in the Django, Javascript and Handlebars files to verify that translations work.

TODOs:

1. Documentation about how the language pack building process works. Use the i18n doc as a starting place.
2. Manually test if handlebars templates are translated.