more doc

Author: erral

docs/i18n-l10n/contributing-translations.md

@@ -17,3 +17,38 @@ How to contribute to the Plone translations.
 
 ## Introduction
 
+Request write access to https://github.com/collective/plone.app.locales to be able to commit your translation directly.
+
+To do so, [join the collective GitHub organization](https://collective.github.io/).
+
+You can fork the repository and work from there or create a new branch and work in that branch.
+
+## Translate Plone
+
+The process of translating Plone UI is the following:
+
+1. Go to https://github.com/collective/plone.app.locales and clone it into your computer
+
+2. Create a new branch to work on your translations. Name the branch with something identifiable. For example: {language}-{date} (ex. fr-20220731)
+
+3. Translate the `po` files under your language of choice at plone/app/locales/locales/{language_code}/LC_MESSAGES/*.po. In Classic UI we have several language files because some of the original messages are spread over several language domains and products.
+
+4. Commit your changes and add a Pull Request with them. Try to have a review from a colleague, specially in case you are translating a file with already some translations. This is just to have coherent translations all over Plone.
+
+
+## Translate Volto
+
+The process of translating Volto UI is the following:
+
+1. Go to https://github.com/plone/volto 3 and clone it into your computer
+2. Create a new branch to prepare the translations. Name the branch with something identifiable. For example: {language}-{date} (ex. fr-20220731)
+
+3.a Translate your language `po` file found at locales/{language_code}/LC_MESSAGES/volto.po
+
+3.b Alternatively, if your language file doesn't exist, create a new folder at locales/{language_code}/LC_MESSAGES/, copy over the volto.pot file there as volto.po and start translating.
+
+4. Commit your changes and add a Pull-Request.
+
+## Support
+
+Please ask questions on the Plone Community Forum category [Translations and i18n/l10n](https://community.plone.org/c/development/i18nl10n/42).

docs/i18n-l10n/index.md

@@ -146,5 +146,6 @@ translating-text-strings
 language-negotiation
 translating-content
 contributing-translations
+resync-translations
 ```
 

docs/i18n-l10n/resync-translations.md

@@ -0,0 +1,86 @@
+---
+html_meta:
+  "description": "How to create po files from source code."
+  "property=og:description": "How to create po files from source code."
+  "property=og:title": "Resync translations"
+  "keywords": "Plone, Internationalization, i18n, language, translate, content, localization"
+---
+
+(resync-translations-label)=
+
+## Resync translations
+
+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.
+
+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.
+
+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.
+
+```bash
+./bootstraph.sh
+```
+
+3. Run buildout using the `experimental/i18n.cfg` file:
+
+```bash
+./bin/buildout -c experimental/i18n.cfg
+```
+
+4. Run the `i18n-update-all` script:
+
+```bash
+./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.
+
+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
+```
+
+## 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:
+
+1. Create a virtualenv with zest.releaser and zest.pocompile installed:
+
+```bash
+`which python3.8` -m venv .
+./bin/pip install zest.releaser zest.pocompile
+source bin/activate
+```
+
+2. Go to plone.app.locales directory and pull the changes:
+
+```bash
+cd src/plone.app.locales
+git pull
+```
+
+3. Verify there is a changelog entry for each change, add any missing entries if necessary.
+
+
+4. Verify there is no errors in the po files:
+
+```bash
+    for po in `find . -name "*.po"` ; do msgfmt --no-hash -o `dirname $po`/`basename $po .po`.mo $po; done
+```
+
+You can ignore the errors "'msgid' and 'msgstr' entries do not both end with '\n'". If there are other errors, please fix them.
+
+5. Release:
+
+```bash
+fullrelease
+```
+
+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