Add a GitHub Action

[mgeisler]

We should publish our own GitHub Action to make it easy to use mdbook-i18n-helpers.

This will move logic from the YAML file (such as publish.yml) to the action. The action is probably written in TypeScript (I'm not sure we can write an action in Rust?) and this will be a more comfortable language than what we can do with scripts in the YAML file.

[mgeisler]

What should a GitHub action do?

• it should download a pre-compiled mdbook-gettext binary so that mdbook build can be fast.
• when Build translations from mdbook #84 is done, the action should also download a pre-compiled version of the new binary there.

Where do these pre-compiled binaries come from? We will need to generate and publish them as part of a release workflow for this repository. See #78 for another issue about releasing binaries.

I would like us to use mgeisler/rust-release-gh-action to do the releases — it's the release flow I'm using for all my Rust crates these days. This release workflow needs to be integrated and it needs to be extended to generate binaries. It should probably also be rewritten as a Rust binary instead (which we will execute via a Dockerfile GitHub action.

So, all in all, there is a fair amount of steps to be tackled here by someone... it will involve touching several interesting technologies 😄

[trooper2013]

@mgeisler Could you please assign this task to me.

[mgeisler]

Hey @trooper2013, thanks a lot for looking at this!

I would love for you to start simple here: building a fully automatic publishing pipeline is complicated, but making a very simple GitHub action is not.

See https://github.com/dprint/check as a good example of how to get started. The action.yml file there installs the dprint command line and runs it. In our case, "installing" means running cargo install mdbook-i18n-helpers at first 🙂

[carreter]

@trooper2013 are you still working on this? If not I can take a shot at it.

[carreter]

@mgeisler If I'm understanding correctly, this action should do the following (modeled after publish.yml from Comprehensive Rust):

• Install mdbook
• Install mdbook-i18n-helpers and dependencies
  • I know of gettext, anything else?
• Generate an updated po/messages.pot file with mdbook-xgettext
• Optionally: Update any existing translations with msgmerge and commit to the repo
• Generate translations for all configured languages
• Generate translations report

The user would then be able to add a job to their workflow like so:

jobs:
    publish:
        steps:
            - name: Checkout
              uses: actions/checkout@v4
            - name: Build translations
              uses: <our new action>
              with:
                  languages: <space-separated list of languages>

Now that I'm thinking about it, maybe this belongs in a separate repo that would also include a GitHub Action to build with mdbook without translations (if that doesn't already exist).

[trooper2013]

@carreter unfortunately I have not got to it. Please re-assign

[mgeisler]

Hi @carreter, thanks for looking at this!

@mgeisler If I'm understanding correctly, this action should do the following (modeled after publish.yml from Comprehensive Rust):

• Install mdbook

• Install mdbook-i18n-helpers and dependencies

  • I know of gettext, anything else?

For Comprehensive Rust, we install our dependencies using action.yml. There are quite a few and it's a mix of what that specific book needs and what mdbook-i18n-helpers need.

Now that I think of it: mdbook-i18n-helpers don't need any of the Gettext binaries: mdbook-gettext is the mdbook plugin you run when you want translate the book in mdbook build. The input to mdbook-gettext is a PO file.

The other mdbook plugin, mdbook-xgettext also doesn't need Gettext: it gets all the Mardown text from the book and produces a POT file.

The Gettext tooling is needed around the mdbook-i18n-helper plugins: you will want to run msgmerge to update the PO file from a fresh POT file at regular intervals.

• Generate an updated po/messages.pot file with mdbook-xgettext

My thinking so far has been that this is something people should do locally when needed. But you have a point that some projects might want to instead auto-generate this in an action and commit it to their repository. That would make it super easy for someone else to start a new translation.

• Optionally: Update any existing translations with msgmerge and commit to the repo

I think this is something that should be done by hand: you need a translator to look over the changes and it's much easier to do this when you have the diff available.

• Generate translations for all configured languages
• Generate translations report

The user would then be able to add a job to their workflow like so:

jobs:
    publish:
        steps:
            - name: Checkout
              uses: actions/checkout@v4
            - name: Build translations
              uses: <our new action>
              with:
                  languages: <space-separated list of languages>

I will suggest two actions:

• One which installs a precompiled mdbook binary.
• Another which installs a precompiled mdbook-gettext binary.

That should be enough to speed up the builds of most (all?) projects that use this translation infrastructure. I think that also makes the task here more self-contained: it basically becomes a question of automating binary releases. I have seen other Rust projects do this, but I haven't looked into the details of how they actually do it 😄

Now that I'm thinking about it, maybe this belongs in a separate repo that would also include a GitHub Action to build with mdbook without translations (if that doesn't already exist).

A separate repository might be a good idea, not super sure! Just as a heads up: there is a bit of process involved on my side if we are going to host this in the google GitHub organization. So if we can use a subdirectory of this repository first, then that will be easier overall.

[carreter]

Sounds good. I'll work on automating binary releases for both mdbook and mdbook-i18n-helpers!