Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[doc] Describe how to work with the pybabel CLI #1050

Open
tomschr opened this issue Dec 15, 2023 · 1 comment
Open

[doc] Describe how to work with the pybabel CLI #1050

tomschr opened this issue Dec 15, 2023 · 1 comment

Comments

@tomschr
Copy link

tomschr commented Dec 15, 2023

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
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants