Translation Guide for Lookit (Draft)

[bleonar5]

Translation Guide for Lookit

Thank you for your interest in translating Lookit! Your contribution will help make our platform accessible to more families around the world. This guide will walk you through the process of translating both the main website interface and the experiment builder.

Types of Translation

There are two separate components that require translation:

1. Website Translation (using Django's gettext)
2. Experiment Builder Translation (using YAML files)

Website Translation (lookit-api)

Prerequisites

• Git and GitHub account
• Python 3.9
• Basic understanding of Git workflow

Steps

1. Fork and Clone the Repository

   • Fork the [lookit-api repository](https://github.com/lookit/lookit-api) on GitHub
   • If you already forked the repo previously, sync your fork with the upstream repository:

     git remote add upstream https://github.com/lookit/lookit-api.git
     git fetch upstream
     git checkout develop
     git merge upstream/develop
     git push origin develop

   • Clone your fork locally: git clone https://github.com/YOUR_USERNAME/lookit-api.git
   • Create a branch for your translation: git checkout -b translation-LANGUAGE_CODE

2. Set Up Environment

   • Create a new Python 3.9 virtual environment:

     python3.9 -m venv clean_env

   • Install dependencies:

     pip install setuptools==68.2.2 wheel==0.41.2 build==1.0.3

   • Install project dependencies with Poetry:

     •  python -m poetry install

3. Generate Translation Files

   • Activate your virtual environment:

     source env/bin/activate

   • Run the following command, replacing <LANGUAGE_CODE> with the ISO language code for your language (e.g., 'es' for Spanish, 'de' for German):

     poetry run python ./manage.py makemessages -l <LANGUAGE_CODE>

4. Edit Translation Files

   • Navigate to the locale directory in the project
   • Find your language folder (e.g., /locale/<LANGUAGE_CODE>/LC_MESSAGES/)
   • Edit the django.po file with your translations

5. Translation Format

   • Each string to translate will look like this:

     #: accounts/forms.py:289
     msgid "Original English string"
     msgstr ""
     

   • Add your translation between the quotes in the msgstr line:

     #: accounts/forms.py:289
     msgid "There's an update about a study we participated in (for example, results are published)"
     msgstr "Es gibt ein Update zu einer Studie, an der wir teilgenommen haben (z. B. werden Ergebnisse veröffentlicht)"
     

   • Keep any formatting placeholders like {name} or %s in your translations
   • Maintain HTML tags such as <strong> or <a href="..."> in the same order

6. Compile Messages

   • After completing your translations, compile them:

     poetry run python ./manage.py compilemessages

   • This step validates your translations and checks for syntax errors

7. Commit and Create Pull Request

   • Commit your changes: git add locale && git commit -m "Add <LANGUAGE_NAME> translation"
   • Push to your fork: git push origin translation-LANGUAGE_CODE
   • Create a Pull Request on GitHub with a clear description of your translation contribution

Experiment Builder Translation (ember-frame-player)

Prerequisites

• Git and GitHub account
• Basic understanding of YAML format

Steps

1. Fork and Clone the Repository

   • Fork the [ember-frame-player repository](https://github.com/lookit/ember-frame-player) on GitHub
   • Clone your fork locally: git clone https://github.com/YOUR_USERNAME/ember-frame-player.git
   • Create a branch for your translation: git checkout -b translation-LANGUAGE_CODE

2. Create Translation File

   • Navigate to the translations directory
   • Create a new file named <LANGUAGE_CODE>.yaml (e.g., de.yaml for German)
   • Copy the structure from en-us.yaml as a template

3. Translate YAML Content

   • The YAML file uses a key-value structure where keys should remain unchanged
   • Replace all English values with corresponding translations in your language
   • Example:

     # Original in en-us.yaml
     Replay: Replay
     
     # Your translation file
     Replay: Repetir   # (for Spanish)

   • Maintain any formatting in the strings like HTML tags or Lookit-specific placeholders

4. Test Your Translations (if possible)

   • If you have a local development environment for the ember app, you can test your translations
   • Otherwise, carefully review for any syntax errors in your YAML file

5. Commit and Create Pull Request

   • Commit your changes: git add translations/<LANGUAGE_CODE>.yaml && git commit -m "Add <LANGUAGE_NAME> translation"
   • Push to your fork: git push origin translation-LANGUAGE_CODE
   • Create a Pull Request on GitHub with a clear description of your translation contribution

Translation Tips

1. Consistency: Keep terminology consistent throughout the translation
2. Context: Consider the context in which strings appear (if unclear, you can ask in your PR)
3. Placeholders: Preserve any {variables} and HTML tags in their original positions
4. Length: Be mindful that some UI elements may have space constraints
5. Cultural Sensitivity: Adapt idioms or cultural references appropriately
6. Review: Check your translations for spelling and grammar errors

Example YAML Structure

The YAML file for experiment builder translations follows this structure (excerpt from en-us.yaml):

No: No
Yes: Yes
Next: Next
Previous: Previous
Replay: Replay
Pause: Pause

exp-lookit-exit-survey:
    confirm-birthdate: Please confirm your child's birthdate
    why-birthdate: We ask again just to check for typos during registration or accidental selection of a different child at the start of the study.
    # more keys...

Getting Help

If you encounter any issues or have questions about the translation process, please:

1. Check if there's an existing issue on GitHub that addresses your question
2. Create a new issue with your question, making sure to mention it's related to translations
3. Reach out to the Lookit team at lookit@mit.edu

Thank you for helping make Lookit accessible to more families around the world!

[bleonar5]

@becky-gilbert I suspect that there are additional steps that may need to be added to this? For instance, is there a variable or object containing available language codes that needs to be updated when a new language is added? Or is adding the new translations to the directory enough?

For the django translations, how would one test how the translations look in a local version? Is there a variable that gets updated for this, or is it something we append to the url in some way to get the translated pages?

[naveenajackson]

Issue still here