[doc] Describe how to work with the pybabel CLI

[tomschr]

Overview Description

The documentation contains the description of the pybabel CLI at https://babel.pocoo.org/en/latest/cmdline.html. It's a reference that describes the command line options.

As I'm not very familiar with the translation process by pybabel I was confused what to do. Unfortunately, the reference doesn't help you when you want to create translations. You search for a procedure.

What's missing in my humble opinion is how to use this tool. How do I create a translation/message catalog, compile it, and update it? Which steps do I need?

Steps to Reproduce

See the documentation.

Actual Results

There is only the reference documentation. How to work with pybabel is missing.

Expected Results

I'd suggest to describe the use cases of pybabel a bit more. This could be added into the "Working with Message Catalogs" topic, for example.

I see the following use cases:

1. Prepare your translation environment
   What do you need? Which configuration options are required? All the things you need before you start.
2. Create translations
   What does the user needs to execute?
3. Integrate it into a Jinja template
   To some degree, it's mentioned. However, IMHO, what's missing is what functions etc. are needed on the Jinja part.
4. Update translations
   When new strings are available, what steps are needed to update your translations?

---

I figured it out to some degree and it seems to work. Maybe there is a more efficient way to do it or something is missing. Let me know if this is the case.

Here are the (sub)sections that could be integrated into the existing pybabel documentation. Certainly, you need to adapt some sentences, terms etc.

Prepare your translation environment

1. Make sure you have pybabel installed. See section XYZ for all requirements.

2. Create a directory, for example translations/, where all your translations are stored.

3. Create a babel.cfg file with the following content:

   [jinja2: **.html.jinja2]
   encoding = utf-8
   ignore_tags = script,style
   include_attrs = alt title summary
   keyword = trans

4. Make sure you name your Jinja2 templates with the file extension .html.jinja2. You can use another file extension if you want, but add it in the babel.cfg file.

Create translations

In order to make pybabel load your translations you need to provide a MO file. For efficiency reasons, it's a binary format. Follow these steps to create this format:

1. Make sure you have prepared your translation environment as described in "Prepare your translation environment"

2. Ensure you have added the {% trans %}...{% endtrans %} block in your Jinja2 templates.
   If you do not have this, pybabel produces empty catalogs.

3. Extract all translatable strings with:

   $ pybabel extract -F babel.cfg \
     --copyright-holder="It's me" --project="My project" \
     *.html.jinja2

   This command creates a messages.pot file in your current directory.

4. Create the translation file with:

   $ pybabel init -d translations -l de

   This command creates a file messages.po in the directory translations/de/LC_MESSAGES/.

5. Translate the PO file
   Use KDE's lokalize or any other tool that can read the PO format.

6. Repeat step 4 + 5 for other languages.

7. Compile PO to MO.

   $ pybabel compile -d translations/ -l de
   compiling catalog translations/de/LC_MESSAGES/messages.po to translations/de/LC_MESSAGES/messages.mo

Update translations

If you add or remove translatable strings from your Jinja2 templates, you need to update your translations as well.

1. Extract all translatable strings with:

   $ pybabel extract -F babel.cfg \
     --copyright-holder="It's me" --project="My project" \
     *.html.jinja2

2. Update the catalog translations:

   $ pybabel update -d translations -i messages.pot
   updating catalog translations/de/LC_MESSAGES/message.po based on docserv.pot
   updating catalog translations/es/LC_MESSAGES/message.po based on docserv.pot

3. Translate the PO file.

4. Compile PO to MO:

   $ pybabel compile -d translations/ -l de
   compiling catalog translations/de/LC_MESSAGES/messages.po to translations/de/LC_MESSAGES/messages.mo

Reproducibility

See documentation.

Additional Information

n/a

[robertlagrant]

It definitely would be good to improve the documentation for first-time users. I'm reading it fresh and have no idea what to do. I think it's been written for people who used gettext previously and now want a simpler experience, rather than for first time translators.