freedomofpress
Consolidate, review and update i18n and l10n docs
(this issue was raised at the 2020-01-14 engineering meeting)
Describe the change
Localization and internationalization documentation is dispersed across various sections:
- https://docs.securedrop.org/en/stable/development/i18n.html
- https://docs.securedrop.org/en/stable/development/l10n.html
Release management for i18n (https://docs.securedrop.org/en/stable/development/i18n.html#release-management) are not included in the release management section (https://docs.securedrop.org/en/stable/development/release_management.html).
A reader may also benefit ### from an overview (perhaps including a diagram) of the various systems and files and flows that are relevant to internationalization (weblate, i18n_tool, babel, .po files etc...)
I have no context about what points were raised during the meeting, but from my perspective this part of the documentation is indeed not easy to digest for a few reasons:
- it touches on multiple aspects of the internationalization and localization work (I'll say the "translation work" going forward)
- it is not that easy to understand what those are without browsing multiple pages
- some of the content is relevant to different people (regular translator, occasional translator, developer, release manager?)
- some of the content is relevant at different times (initial setup as a translator, development time, release time, first contact with SecureDrop...)
- it feels dispersed across multiple sections (I have a similar feeling, but I'm not sure that having multiple sections is a problem in itself.)
Considering @emkll's observation that the translation docs require being reviewed, updated and extended, and the fact that it's a couple of pages in total and the topic is relatively self-contained, I think these pages could be an opportunity to give a try to:
- Splitting the existing content by topic and after Divio's documentation system (tutorial, reference, how-to, explanation)
- Consolidating the resulting "documents" in a section of their own so they can be consumed individually, but are organized as a whole.
I would expect the outcome of this to be a body of documentation that:
-
is easier to consume for different people with different purposes (studying, working)
-
is easier to maintain (more modular, clearer goals for each piece of content)
I couldn't visualize the changes well enough to draft what a table of content could look like, so I decided to spike the idea with the actual content instead. I think things don't look too bad and I'd personally give it a go, but I let you judge if that's a direction worth exploring further.
Draft PR follows.
@emkll @eloquence @rmol Heads up this issue was closed because I mentioned it in the description of #141 that was recently merged.
Translations were worked on, but not i18n / release management, so you may want to cross-check if this issue fulfilled its role already or maybe should be re-opened.
