Clean up formatting of resync-translations.md

Author: stevepiercy

docs/i18n-l10n/resync-translations.md

@@ -8,97 +8,111 @@ html_meta:
 
 (resync-translations-label)=
 
-## Resync translations in Plone back-end
+## Resync translations in the Plone backend
 
-Plone po files need to be updated each time a new string is added into Plone interface, or each time one of those strings is updated. Those translations are not only used in Plone Classic, but many of them are also exposed through the REST API to Volto.
+Plone {term}`PO file`s need to be updated each time a new string is added into the Plone interface or each time one of those strings is updated.
+Those translations are not only used in Plone Classic UI, but many of them are also exposed through the REST API to Volto.
 
-Usually Translations team handles the update of those po files so you don't need to worry about it. Here we will explain the procedure to update such files.
+Usually the Plone Translations Team updates these PO files.
+Here we will explain the procedure to update them.
 
-1. Clone the relevant branch of [buildout.coredev](https://github.com/plone/buildout.coredev) corresponding to the Plone version you want to update.
+1.  Clone the relevant branch of [buildout.coredev](https://github.com/plone/buildout.coredev) corresponding to the Plone version you want to update.
 
-2. Initialize the buildout.
+2.  Initialize the buildout.
 
-```bash
-./bootstraph.sh
-```
+    ```shell
+    ./bootstraph.sh
+    ```
 
-3. Run buildout using the `experimental/i18n.cfg` file:
+3.  Run buildout using the `experimental/i18n.cfg` file:
 
-```bash
-./bin/buildout -c experimental/i18n.cfg
-```
+    ```shell
+    ./bin/buildout -c experimental/i18n.cfg
+    ```
 
-4. Run the `i18n-update-all` script:
+4.  Run the `i18n-update-all` script:
 
-```bash
-./bin/i18n-update-all
-```
+    ```shell
+    ./bin/i18n-update-all
+    ```
 
-The script will go through Plone source code and will update all `pot` and `po` files in the plone.app.locales package.
+    The script will go through Plone source code and will update all `pot` and `po` files in the `plone.app.locales` package.
 
-5. Commit the changes and push back to GitHub:
+5.  Commit the changes and push back to GitHub:
 
-```bash
-cd src/plone.app.locales
-git add plone
-git commit -m "Update translation files"
-git push origin
-```
+    ```shell
+    cd src/plone.app.locales
+    git add plone
+    git commit -m "Update translation files"
+    git push origin
+    ```
 
-## Create a new plone.app.locales release
 
-Translators will take care of translating `po` files into their languages. When the release manager requests to create a new plone.app.locales release, the procedure is the following:
+(create-new-plone.app.locales-release-label)=
 
-1. Create a virtualenv with zest.releaser and zest.pocompile installed:
+## Create a new `plone.app.locales` release
 
-```bash
-`which python3.8` -m venv .
-./bin/pip install zest.releaser zest.pocompile
-source bin/activate
-```
+Translators will take care of translating `po` files into their languages.
+When the release manager requests to create a new `plone.app.locales` release, the procedure is the following:
 
-2. Go to plone.app.locales directory and pull the changes:
+1.  Create a virtualenv with `zest.releaser` and `zest.pocompile` installed:
 
-```bash
-cd src/plone.app.locales
-git pull
-```
+    ```shell
+    `which python3.10` -m venv .
+    ./bin/pip install zest.releaser zest.pocompile
+    source bin/activate
+    ```
 
-3. Verify there is a changelog entry for each change, add any missing entries if necessary.
+2.  Go to the `plone.app.locales` directory and pull the changes:
 
+    ```shell
+    cd src/plone.app.locales
+    git pull
+    ```
 
-4. Verify there is no errors in the po files:
+3.  Verify there is a changelog entry for each change, adding any missing entries if necessary.
 
-```bash
-    for po in `find . -name "*.po"` ; do msgfmt --no-hash -o `dirname $po`/`basename $po .po`.mo $po; done
-```
+4.  Verify there are no errors in the PO files:
 
-You can ignore the errors "'msgid' and 'msgstr' entries do not both end with '\n'". If there are other errors, please fix them.
+    ```shell
+        for po in `find . -name "*.po"` ; do msgfmt --no-hash -o `dirname $po`/`basename $po .po`.mo $po; done
+    ```
 
-5. Release:
+    You can ignore the errors `'msgid' and 'msgstr' entries do not both end with '\n'`.
+    If there are other errors, please fix them.
 
-```bash
-fullrelease
-```
+5.  Release.
+
+    ```shell
+    fullrelease
+    ```
+
+6.  Check that the release is published on PyPI at https://pypi.org/project/plone.app.locales/.
 
-6. Check that the release is published on pypi: https://pypi.org/project/plone.app.locales/
+7.  Inform the release manager about the new version.
 
-7. Inform the release manager about the new version
 
-## Resync of translations in Volto
+(resync-translations-volto-label)=
 
-In Volto, the GitHub test setup warns a developer when her new bits require regenerating the translation file. This is done running a yarn script as follows:
+## Resync translations in Volto
 
-```bash
+In Volto, the GitHub test setup warns a developer when their new contributions require regenerating the translation file.
+This is done by running a yarn script as follows:
+
+```shell
 yarn i18n
 ```
 
-This will update the po files and will leave them ready to be translated by translators.
+This will update the PO files and will leave them ready to be translated by translators.
+
+
+(create-release-volto-translations)=
 
-## Create a new release of Volto with the new translations
+## Create a release of Volto with the new translations
 
-The Volto release process requires running the same yarn script as in the previous step to convert the translations in po files to the JSON files that Volto uses to render the user interface.
+The Volto release process requires running the same yarn script as in the previous step.
+It will convert the translations in PO files to the JSON files that Volto uses to render the user interface.
 
-```bash
+```shell
 yarn i18n
 ```