diff --git a/docs/how_tos/i18n.rst b/docs/how_tos/i18n.rst index 073f460cf..7d17c6ff5 100644 --- a/docs/how_tos/i18n.rst +++ b/docs/how_tos/i18n.rst @@ -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/.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 `__ repo, but you don't have to modify them. They will interact with your repo through ``make`` targets. - -#. Copy the `frontend-app-account 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 `__. - -*********************************** -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 `__. 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 `__, 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 `_ 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 `_ on `docs.openedx.org `_. ****************************** Load up your translation files