Should we use gettext for RST files?

[emlys]

In the first iteration of translating the user's guide, we're using sphinx-intl and the sphinx gettext builder to manage translations following the gettext pattern (message catalogs, etc.). We also considered having the RST files translated directly, and not using gettext. We should revisit this decision once we've gone through the translation process.

gettext

pros

• gettext message catalogs are the standard: any translator or service should accept them
• single RST file is single source of truth for the document's RST markup

cons

• somewhat complicated process to extract messages and update translations
• gettext tools for RST are imperfect. no way to exclude things that shouldn't be translated e.g. tables, equations, references. the tools are not super well supported and I noticed a minor bug already.

directly translate RST files

We would send the translator our RST files (and a diff showing what's changed since the last time they were translated).

pros

• less maintenance for us
• translator sees complete context for text

cons

• need a translator who is comfortable working with RST and git diffs
• no single source of truth for RST markup - changes in RST markup would not be reflected in the translated pages until the next round of translation (or this would have to be done manually)

Which is more cost-effective really depends on the translator and how they bill us. If they can work with RST files and git diffs, that could be very efficient.