translation.md

Translation

(Return to primary ../README.md.)

Overview

To upload/download translation files to/from Transifex, you'll need an account there with access to these translations. Then follow the Authentication - Transifex API v3: to get an API token, and set TRANSIFEX["API_TOKEN"] in your environment with its value.

The creativecommons/cc-legal-tools-data repository must be cloned next to this cc-legal-tools-app repository. (It can be elsewhere, then you need to set DATA_REPOSITORY_DIR to its location.) Be sure to clone using a URL that starts with git@github... and not https://github..., or you won't be able to push to it. See ../README.md for details.

In production, the check_for_translation_updates management command should be run hourly. See Check for Translation Updates, below.

Also see Publishing changes to git repo, below.

Babel is used for localization information.

Documentation:

• Babel — Babel documentation
• Translation | Django documentation | Django

How the tool translation is implemented

Django Translation uses two sets of Gettext Files in the creativecommons/cc-legal-tools-data repository (the Data Repository, above). See that repository for detailed information and definitions.

Documentation:

• Translation | Django documentation | Django
• Transifex API
  • Introduction to API 3.0 | Transifex Documentation
  • Transifex API v3
  • Python SDK: transifex-python/transifex/api

Add translation

1. Add language to appropriate resource in Transifex
2. Ensure language is present in Django
   • If not, update cc_legal_tools/settings/base.py
3. Add objects for new language translation using the add_translation management command.
   • Examples:

     docker compose exec app ./manage.py add_translation -v2 --licenses -l tlh

     docker compose exec app ./manage.py add_translation -v2 --zero -l tlh

4. Synchronize repository Gettext files with Transifex
5. Compile .mo machine object Gettext files:

   docker compose exec app ./manage.py compilemessages

Documentation:

• Quick start guide — polib documentation
• Also see How the tool translation is implemented documentation, above

Synchronize repository Gettext files with Transifex

• TODO document processes of synchronizing the repository Gettext files with Transifex, including the following management commands:
  • locale_info
  • normalize_translations
  • compare_translations
  • pull_translation
  • push_translation
  • compilemessages

Check for translation updates

⚠️ This functionality is currently disabled.

The hourly run of check_for_translation_updates looks to see if any of the translation files in Transifex have newer last modification times than we know about. It performs the following process (which can also be done manually:

1. Ensure the Data Repository (../README.md) is in place
2. Within the creativecommons/cc-legal-tools-data (the Data Repository):
   1. Checkout or create the appropriate branch.
      • For example, if a French translation file for BY 4.0 has changed, the branch name will be cc4-fr.
   2. Download the updated .po portable object Gettext file from Transifex
   3. Do the Translation Update Process (below)
      • This is important and easy to forget, but without it, Django will keep using the old translations
   4. Commit that change and push it upstream. 3.~~ Within this cc-legal-tools-app repository:~~
   5. For each branch that has been updated, Generate Static Files (../README.md). Use the options to update git and push the changes.

Documentation:

• GitPython Documentation — GitPython documentation
• Requests: HTTP for Humans™ — Requests documentation