Document translation workflow

[micha030201]

FlaskBB has extensive internationalization support, and several translations already. However, there's still much to be desired. After examining flaskbb's translation practices, I've found the following issues:

It's not clear what translators are supposed to do

After digging in the source files, I discovered that flaskbb uses transifex for crowdsourced translations. This needs to be documented in CONTRIBUTING.md to make it as easy for potential contributors to discover as possible.

There's no styleguide for translations, and it's not documented what's expected of translators. Let's say I want to assist in translating flaskbb to Russian (which, coincidentally, I do; that's my native language and I'd easily be able to translate the entirety of flaskbb to it). How would I go about doing that? Am I supposed to just start translating strings at random the way I feel like it, or is there some sort of system to it? If I find a particular string badly-translated (which, coincidentally, I have; a large portion of the Russian translation is done inconsistently/incorrectly), should I just replace it or do I have to coordinate that with someone? What about style changes?

It doesn't seem to be documented anywhere how/if the translations are proofread, and when they are pulled into the repository. Is that only done on releases? How can I, as a translator, learn when the next release is and when the translation should be finished?

When are the source, untranslated files uploaded to transifex? As a translator, how can I know I'm working on an up-to-date file?

How can I, as a translator, know where a particular string will be used? How do I tell if 'Login' is used as a verb ('click here to login') or as a noun ('enter your login')? This ambiguity leads to a lot of problems in the Russian translation; nouns are translated as verbs and vice-versa. Is there any way to see how the translation looks on a local copy of flaskbb, or do I have to wait until the next release to catch any contextual errors like this?

If I want to contribute a translation to one of flaskbb's stock plugins (Portal or Conversations), how would I go about doing that?

It's not clear what programmers are supposed to do

If I change/add a translatable string in a pull request, am I supposed to extract the new messages.pot file? If not, how often is that done, and by whom?

What strings should be translated? Do we translate console help messages? Do we translate errors?

If I change/add a string, and can translate it to a given language myself, am I able to do that as part of the same pull request, or will that be overridden by transifex?

It's not clear what plugin developers are supposed to do

No currently existing flaskbb plugin supplies translations. In fact, as of the current master, no flaskbb plugin can supply translations, something #505 is meant to address. That not only makes them difficult to use for people who set their forum/account to a different language, but also makes adding translations to new plugins more challenging, as there's no reference to consult.

There's no documentation for how one would go about translating a plugin. Given that most plugin developers probably aren't polyglots, do we expect them to use transifex as well? If so, the basic steps for doing that should be documented, the way other plugin development nuances are.

---

Thank you for reading this. I understand that these issues require quite a lot of work to solve, whether by writing documentation or otherwise, but I'm convinced they must be solved nevertheless, and will gladly help in whatever ways I can.

[ppker]

good. I myself agree with you