feat: create i18.sh script and hook it to github action

- The script runs on merge, will generate .tx directory.
- .tx contains transifex config files of *specific* edx-doc projects,
the files will be used by tx-client in order to push resources.
- Both sphinx-intl and tx-client libraries are being used and thus are
 added to the dependency.
- TX_TOKEN is expected to be available in the env with push permission,
 for more info refer to:
  https://docs.transifex.com/client/client-configuration
- Related ticket: https://trello.com/c/q4JJOHeo

Author: ghassanmas

.github/workflows/build.yml

@@ -38,3 +38,12 @@ jobs:
       - name: "Build docs"
         run: |
           ./run_tests.sh
+
+      - name : "Translations Sync"
+        if: ${{ github.event.pull_request.merged }}
+        env:
+            TX_TOKEN: ${{ secrets.TX_TOKEN }}
+        run: |
+          ./i18n.sh
+          tx push -s
+          

Makefile

@@ -32,3 +32,5 @@ clean: ## remove built html files
 
 test: ## build all the docs
 	./run_tests.sh
+i18n: ## Generate pot files followed by tx configuration
+	./i18n.sh

i18n.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+
+# This script purpose is to ease process needed to support i18n
+# for the doc. It does that by first generating pot from the 
+# rst files of a  selected projects using sphinx to generate gettext
+# (which outputs the pot files) and then the next step
+# is to use sphinx-intl to write to the ./tx/config file, hence
+# this script cerates the ./tx/config file. Note: if the file, 
+# already exists it will be overwritten!.
+# This script assumes sphinx-intl is already installed as well, 
+# It can be installed by `pip install sphinx-intl`
+# For more information, about sphinx-intl please visit: 
+# https://www.sphinx-doc.org/en/master/usage/advanced/intl.html 
+
+
+# Check if this script is running by github, and if it's 
+# missing the token then exit.
+if [ "$CI" = true ] && [ -z "$TX_TOKEN" ]; then
+echo 'Running cancelled, missing TX_TOKEN!'
+exit 1
+fi
+
+# Root directory
+BASE_DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
+# Config file 
+TX_CONFIG_FILE=$BASE_DIR/.tx/config
+
+# Success  exit message, wrapped in green color. 
+EXIT_MESSAGE="\033[0;32mYou should now be able to push the files using tx client \n
+Typically this done by 'tx push -s', please note: you should have \n
+already installed tx client and configured it such that there is \n
+a project called 'open-edx-documentation-project' in the organization \n 
+and that you already have authenticated with in '~/.transifexrc', \n 
+for more  information, please visit: \n
+https://docs.transifex.com/client/client-configuration.\033[0m"
+
+# Preparing the config file: 
+rm -rf .tx 
+mkdir $BASE_DIR/.tx 
+touch $TX_CONFIG_FILE
+echo "[main]" >> $TX_CONFIG_FILE
+echo "host = https://www.transifex.com" >> $TX_CONFIG_FILE
+
+
+# The set of books to run translations for.
+# Currently this is only a subset of the books in this repo because we are in the middle of
+# assesing which books will remain a part of openedx and which ones are actually specific
+# to edx.org
+projects=(
+    "en_us/open_edx_students"
+    "en_us/open_edx_course_authors"
+    "en_us/open_edx_release_notes"
+    )
+
+# Iterating over each project defined above, to generate the pot the files
+# and then mapping the files accordingly in the tx config file
+for project in "${projects[@]}"; do
+    cd $BASE_DIR/$project
+    echo "--> Start generating the pot files for ${project#'en_us/'}"
+
+    # Extract translatable messages into pot files 
+    make gettext
+
+    # Adding the pot files to tx config file 
+    echo "--> Start writing tx configuration for the ${project#'en_us/'}"
+
+    cd $BASE_DIR
+    sphinx-intl update-txconfig-resources \
+    --pot-dir $BASE_DIR/$project/build/locale/ \
+    --locale-dir $BASE_DIR/$project/locales/ \
+    --transifex-project-name open-edx-documentation-project
+done
+
+# Todo: Check for errors and set exit message accordingly
+
+echo -e ${EXIT_MESSAGE}
+
+

requirements/base.in

@@ -3,3 +3,5 @@
 
 edx-sphinx-theme                    # edX theme for the generated documentation
 sphinx                              # Documentation builder
+sphinx-intl                         # For creating i18n strings
+transifex-client                    # For pushing the i18n resources

requirements/base.txt

@@ -1,49 +1,66 @@
 #
-# This file is autogenerated by pip-compile
+# This file is autogenerated by pip-compile with python 3.8
 # To update, run:
 #
 #    make upgrade
 #
 alabaster==0.7.12
     # via sphinx
 babel==2.9.1
-    # via sphinx
-certifi==2021.5.30
-    # via requests
-chardet==4.0.0
-    # via requests
-docutils==0.16
     # via
-    #   -c requirements/common_constraints.txt
     #   sphinx
-edx-sphinx-theme==2.1.0
+    #   sphinx-intl
+certifi==2021.10.8
+    # via requests
+charset-normalizer==2.0.9
+    # via requests
+click==8.0.3
+    # via sphinx-intl
+docutils==0.17.1
+    # via sphinx
+edx-sphinx-theme==3.0.0
     # via -r requirements/base.in
-idna==2.10
+gitdb==4.0.9
+    # via gitpython
+gitpython==3.1.24
+    # via transifex-client
+idna==3.3
     # via requests
-imagesize==1.2.0
+imagesize==1.3.0
     # via sphinx
-jinja2==3.0.1
+jinja2==3.0.3
     # via sphinx
 markupsafe==2.0.1
     # via jinja2
-packaging==20.9
+packaging==21.3
     # via sphinx
-pygments==2.9.0
+pygments==2.10.0
     # via sphinx
-pyparsing==2.4.7
+pyparsing==3.0.6
     # via packaging
-pytz==2021.1
+python-slugify==4.0.1
+    # via transifex-client
+pytz==2021.3
     # via babel
-requests==2.25.1
-    # via sphinx
+requests==2.26.0
+    # via
+    #   sphinx
+    #   transifex-client
 six==1.16.0
-    # via edx-sphinx-theme
-snowballstemmer==2.1.0
+    # via
+    #   edx-sphinx-theme
+    #   transifex-client
+smmap==5.0.0
+    # via gitdb
+snowballstemmer==2.2.0
     # via sphinx
-sphinx==4.0.2
+sphinx==4.3.1
     # via
     #   -r requirements/base.in
     #   edx-sphinx-theme
+    #   sphinx-intl
+sphinx-intl==2.0.1
+    # via -r requirements/base.in
 sphinxcontrib-applehelp==1.0.2
     # via sphinx
 sphinxcontrib-devhelp==1.0.2
@@ -56,8 +73,16 @@ sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
-urllib3==1.26.5
-    # via requests
+text-unidecode==1.3
+    # via python-slugify
+transifex-client==0.14.3
+    # via -r requirements/base.in
+typing-extensions==4.0.1
+    # via gitpython
+urllib3==1.26.7
+    # via
+    #   requests
+    #   transifex-client
 
 # The following packages are considered to be unsafe in a requirements file:
 # setuptools

requirements/common_constraints.txt

@@ -13,14 +13,8 @@
 
 
 # using LTS django version
-Django<2.3
+Django<3.3
 
-# docutils version 0.17 is causing docs rendering to fail
-# See https://sourceforge.net/p/docutils/bugs/417/
-docutils==0.16
-
-# latest version is causing e2e failures in edx-platform.
-drf-jwt<1.19.1
-
-# Newer versions causing tests failures in multiple repos.
-pyjwt[crypto]==1.7.1
+# elasticsearch>=7.14.0 includes breaking changes in it which caused issues in discovery upgrade process.
+# elastic search changelog: https://www.elastic.co/guide/en/enterprise-search/master/release-notes-7.14.0.html
+elasticsearch<7.14.0

requirements/dev.txt

@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile
+# This file is autogenerated by pip-compile with python 3.8
 # To update, run:
 #
 #    make upgrade
@@ -12,74 +12,99 @@ babel==2.9.1
     # via
     #   -r requirements/base.txt
     #   sphinx
-certifi==2021.5.30
+    #   sphinx-intl
+certifi==2021.10.8
     # via
     #   -r requirements/base.txt
     #   requests
-chardet==4.0.0
+charset-normalizer==2.0.9
     # via
     #   -r requirements/base.txt
     #   requests
-click==8.0.1
-    # via pip-tools
-docutils==0.16
+click==8.0.3
+    # via
+    #   -r requirements/base.txt
+    #   pip-tools
+    #   sphinx-intl
+docutils==0.17.1
     # via
     #   -r requirements/base.txt
     #   sphinx
-edx-sphinx-theme==2.1.0
+edx-sphinx-theme==3.0.0
     # via -r requirements/base.txt
-idna==2.10
+gitdb==4.0.9
+    # via
+    #   -r requirements/base.txt
+    #   gitpython
+gitpython==3.1.24
+    # via
+    #   -r requirements/base.txt
+    #   transifex-client
+idna==3.3
     # via
     #   -r requirements/base.txt
     #   requests
-imagesize==1.2.0
+imagesize==1.3.0
     # via
     #   -r requirements/base.txt
     #   sphinx
-jinja2==3.0.1
+jinja2==3.0.3
     # via
     #   -r requirements/base.txt
     #   sphinx
 markupsafe==2.0.1
     # via
     #   -r requirements/base.txt
     #   jinja2
-packaging==20.9
+packaging==21.3
     # via
     #   -r requirements/base.txt
     #   sphinx
-pep517==0.10.0
+pep517==0.12.0
     # via pip-tools
-pip-tools==6.1.0
+pip-tools==6.4.0
     # via -r requirements/dev.in
-pygments==2.9.0
+pygments==2.10.0
     # via
     #   -r requirements/base.txt
     #   sphinx
-pyparsing==2.4.7
+pyparsing==3.0.6
     # via
     #   -r requirements/base.txt
     #   packaging
-pytz==2021.1
+python-slugify==4.0.1
+    # via
+    #   -r requirements/base.txt
+    #   transifex-client
+pytz==2021.3
     # via
     #   -r requirements/base.txt
     #   babel
-requests==2.25.1
+requests==2.26.0
     # via
     #   -r requirements/base.txt
     #   sphinx
+    #   transifex-client
 six==1.16.0
     # via
     #   -r requirements/base.txt
     #   edx-sphinx-theme
-snowballstemmer==2.1.0
+    #   transifex-client
+smmap==5.0.0
+    # via
+    #   -r requirements/base.txt
+    #   gitdb
+snowballstemmer==2.2.0
     # via
     #   -r requirements/base.txt
     #   sphinx
-sphinx==4.0.2
+sphinx==4.3.1
     # via
     #   -r requirements/base.txt
     #   edx-sphinx-theme
+    #   sphinx-intl
+sphinx-intl==2.0.1
+    # via -r requirements/base.txt
 sphinxcontrib-applehelp==1.0.2
     # via
     #   -r requirements/base.txt
@@ -104,12 +129,25 @@ sphinxcontrib-serializinghtml==1.1.5
     # via
     #   -r requirements/base.txt
     #   sphinx
-toml==0.10.2
+text-unidecode==1.3
+    # via
+    #   -r requirements/base.txt
+    #   python-slugify
+tomli==1.2.2
     # via pep517
-urllib3==1.26.5
+transifex-client==0.14.3
+    # via -r requirements/base.txt
+typing-extensions==4.0.1
+    # via
+    #   -r requirements/base.txt
+    #   gitpython
+urllib3==1.26.7
     # via
     #   -r requirements/base.txt
     #   requests
+    #   transifex-client
+wheel==0.37.0
+    # via pip-tools
 
 # The following packages are considered to be unsafe in a requirements file:
 # pip