Open mgeisler opened 1 year ago
What should a GitHub action do?
mdbook-gettext
binary so that mdbook build
can be fast.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 :smile:
@mgeisler Could you please assign this task to me.
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 :slightly_smiling_face:
@trooper2013 are you still working on this? If not I can take a shot at it.
@mgeisler If I'm understanding correctly, this action should do the following (modeled after publish.yml from Comprehensive Rust):
mdbook
mdbook-i18n-helpers
and dependencies
gettext
, anything else?po/messages.pot
file with mdbook-xgettext
msgmerge
and commit to the repoThe 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).
@carreter unfortunately I have not got to it. Please re-assign
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 withmdbook-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:
mdbook
binary.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 :smile:
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.
Sounds good. I'll work on automating binary releases for both mdbook
and mdbook-i18n-helpers
!
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.