Skip to content

Commit

Permalink
docs: update i18n readme to link to OEP-58 docs (#635)
Browse files Browse the repository at this point in the history
  • Loading branch information
@brian-smith-tcril
brian-smith-tcril authored Feb 16, 2024
1 parent 804c8f0 commit 589a448
Showing 1 changed file with 4 additions and 136 deletions.
140 changes: 4 additions & 136 deletions docs/how_tos/i18n.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,143 +76,11 @@ These steps will allow your application to accept translation strings. See `fron

#. You should now be able to run your app and see everything behaving normally, with English strings.

****************
Set up Transifex
****************

In your repo, create and commit a file named ``.tx/config``::

[main]
host = https://www.transifex.com

[edx-platform.your-resource-name-here]
file_filter = src/i18n/messages/<lang>.json
source_file = src/i18n/transifex_input.json
source_lang = en
type = KEYVALUEJSON

*************************
Set up the pipeline tools
*************************

The pipeline jobs live in the `ecommerce-scripts <https://github.com/openedx/ecommerce-scripts/tree/master/transifex>`__ repo, but you don't have to modify them. They will interact with your repo through ``make`` targets.

#. Copy the `frontend-app-account Makefile <https://github.com/openedx/frontend-app-account/blob/master/Makefile>`__ to your project.

* Modify the ``transifex_resource`` variable with your own Transifex resource name.

#. The job to push strings to Transifex will call ``make push_translations`` in your repo. This target should do everything necessary to extract your strings, concat them into one file, and put them in ``src/i18n/transifex_input.json``. If you don't have any special requirements, you can just use the default target that is included ``from frontend-i18n``.

#. Extraction: We will be using a Babel plugin to find all the strings inside a ``FormattedMessage`` component or inside a call to ``defineMessages``.

If you are using @edx/frontend-build...

* Add this to ``scripts`` in ``package.json``::
"i18n_extract": "BABEL_ENV=i18n fedx-scripts babel src --quiet > /dev/null"

* The default babel configuration provided by frontend-build has the needed configuration.

If you are NOT using @edx/frontend-build:

* Add this to ``scripts`` in ``package.json``::

"i18n_extract": "BABEL_ENV=i18n babel src --quiet > /dev/null"

* Add ``babel-plugin-formatjs`` to your dev dependencies::

npm install babel-plugin-formatjs --save-dev

* Add this to ``.babelrc``::

"env": {
"i18n": {
"plugins": [
["react-intl", {
"messagesDir": "./temp/babel-plugin-formatjs",
"moduleSourceName": "@edx/frontend-platform/i18n"
}]
]
}
}

Then:

* Confirm that running ``make i18n.extract`` creates a lot of ``.json`` files in ``your-repo/temp/babel-plugin-formatjs/`` .

* Add ``temp`` and ``src/i18n/transifex_input.json`` to your ``.gitignore``.

#. Concatenation: All those ``.json`` files need to become one file.

* Confirm that running ``make i18n.concat`` creates ``src/i18n/transifex_input.json``, which should be a file of message id / English pairs.

* If you are missing any dependencies, like ``glob``, you will need to add these to your dev dependencies.

#. Uploading comments: The ``KEYVALUEJSON`` format doesn't have a way to put in translator comments (the ``description`` field in your message definitions), so we work around this by making calls to the Transifex API. There isn't a bulk call available, so it will be one API call per string. (...I know.) As of June 2019, the rate limit is 6000 calls per hour.

* Add ``reactifex`` to your dev dependencies::

npm install reactifex --save-dev

* You can't test this one without Transifex credentials, so at this point it's probably easiest to just make your pipeline job and run that.

#. The job to pull translations out of Transifex and commit them to your repo will call ``make pull_translations``.

* If the languages you want to pull down differ from the default set, you can update the ``transifex_langs`` variable in your local Makefile.

* The user ``edx_transifex_bot`` will need to have permissions to merge an unreviewed pull request into your repo. This means your repo must either allow merging unreviewed pull requests for everyone, or ``edx_transifex_bot`` needs to be an administrator.

*******************************************
Create empty translation files in your repo
*******************************************

#. You must commit an empty language file for each language, or the ``pull`` job will fail. Each file is named ``src/i18n/messages/LANG_CODE.json`` and consists of an empty JSON object (``{}``). See this `example code with empty language files <https://github.com/openedx/frontend-component-footer/commit/46772ecc0e8de2ce1815607fdf2e8f2867dc83cf>`__.

***********************************
Create your pipeline job on Jenkins
***********************************

#. Test your change locally.

* __NOTE__: You need the existing project resource on Transifiex or have the priviledge to create it. Otherwise skip to the next step.

* Clone https://github.com/openedx/ecommerce-scripts.

* Create virtualenv for python.

* Install requirements based on the ``requirements`` section on the `tools-edx-jenkins/translation-jobs.yml <https://github.com/edx/edx-internal/blob/master/tools-edx-jenkins/translation-jobs.yml>`__. It should be something similiar to ``pip install -r transifex/requirements/microfrontend-common.txt``.

* Run the script that you try to create the jobs.

* Examples: ``python transifex/pull.py https://github.com/openedx/edx-platform.git``. You might be required to setup environment variable ``GITHUB_ACCESS_TOKEN`` with your personal github account.

* For ``push_translations``, you also need transifex authentication. This action will try to create project resource if it isn't existed yet. If you don't have permission, it will fail.

* For ``pull_translations``, it should try to create a pull request and merge it to the repo.

#. In the ``edx-internal`` repo, add your job to `tools-edx-jenkins/translation-jobs.yml <https://github.com/edx/edx-internal/blob/master/tools-edx-jenkins/translation-jobs.yml>`__, using one of the existing frontend apps as a model.

* Add an opsgenie email address that actually exists :-) so you get notified of failures.

* You will need to set up OpsGenie to properly send these alerts, and to auto-close notifications when Jenkins goes back to normal.

* In the command lines that run the job, put in your repo name and the GitHub team name that you'd like notifications sent to.

* The existing jobs push translation strings to Transifex daily, and pull completed translations once a week, on Sunday. You can pick your own schedule on the ``cron`` line. It's best to move your new job off of 8PM UTC, so we don't have to worry about the Transifex API rate limit described above.

* Note that the Jenkins machine uses UTC.

#. Open a pull request with your change. If you do't have permission or someone to review, you can `open a devops ticket <https://openedx.atlassian.net/servicedesk/customer/portal/3>`_ requesting them to review your pull request and rerun the seed job. Only devops can merge pull requests in this repo.

#. Once the change get merge, you can build https://tools-edx-jenkins.edx.org/job/Seed%20Jobs/job/Translation%20Seed%20Jobs/ to have the change propegated. (You need to connect to the edX VPN)

* If you don't have permission, you can wait for the job to propegate. It takes up to one day.

#. Connect to the edX VPN to see your two new jobs at https://tools-edx-jenkins.edx.org/job/translations/ . ``push_translations`` extracts the strings from your repo and pushes them to Transifex. ``pull_translations`` pulls the translated strings from Transifex and checks them into your repo. You can test these jobs out by running them manually.

* The first job you need to run is ``push_translations``. This would create project resource on Transifex if the resource isn't existed yet.
*************************************************
Add your application to the translations workflow
*************************************************

* If you can't see this page, you might need to be added to the ``jenkins-tools-translation-jobs`` team in GitHub.
Follow the `instructions for including React repositories in the translations workflow <https://docs.openedx.org/en/latest/developers/how-tos/enable-translations-new-repo.html#react-repos>`_ on `docs.openedx.org <https://docs.openedx.org/>`_.

******************************
Load up your translation files
Expand Down

0 comments on commit 589a448

Please sign in to comment.