Building an internationalization friendly project - Documentation

Hi,

I created a basic proof of concept of documentation system to answer one of the internationalization objectives I discussed here:

Current situation

Simone is a static website written in markdown. We currently have French and English pages, but there is no built-in support to jump from one language to another, to keep translated content up to date or to know what is translated and what isn’t.

The proof of concept

Main idea

Use a tool to push English content in one or many po files (to use with https://translate.yunohost.org), then publish translated content by using built-in internalization support.

The perimeter of this proof of concept is the automation of transformation process.

Tools

I decided to use Pelican, a python static generator, in combination with po4a to handle the transform process (en.md → po → translated.md) for the content. And jinja’s (the template system) i18n module in combination with babel.

Demonstration

The source code is available at this address : GitHub - Jibec/Simon: YunoHost documentation using Pelican
The demonstration website is available at this address : YunoHost Portal

The translated website shows:

As a perfectly website was not the goal of this POC, there is not much more to show and you’ll see many css and dead links issues. The interesting part is to add a new English documentation page, edit the po file to translate it (at least 80% is needed for publication) and build the website to see the result.

How will the translator contribute?

They will go to YunoHost’s Weblate and translate the strings. If needed, they can search for the specific markdown file they want to translate by using the Weblate’s context research feature.

SWOT

Strength

  1. Open YunoHost to more languages (we recently received German, Spanish and Italian translation, and German contributors want to translate documentation)
  2. Easy to contribute translation by using YunoHost’s Weblate.
  3. Reuse of long-term maintained tools.
  4. Only minor modification to current documentation is needed.
  5. Easily accessible for search engines.

Weakness

  1. Documentation contributors will have to work in English.
  2. Identify french only documentation and translate it in English po4a may help.
  3. A “slug” (unique id) for each page will have to be produced for each file (must not be translated),

Opportunities

  1. Have a better structure for documentation (I suggested user/administration/contributor/organization)
  2. Clean outdated content, do we really need multiple changelog pages? Shouldn’t we have content for 2.4 and 2.5?
  3. Po makes possible the use of existing consistency checks (translate toolkit, pology, dennis, etc.)
  4. Make documentation sub-site more independent so we can transform it as a YunoHost App.

Threats

  1. Have a better translated content, but less contributors.

Todo

  • Add a text in the template, below content to inform: where to go to contribute English, where to go to correct translated content.
  • Add Simone’s current JavaScript text edition so we can have English content edition as easy as today.
  • Add 404 pages (as the demo is hosted in my server, a 404 brings you back to the sso portal)
  • Add Converse.js or equivalent for in-page XMPP discussion (jappix is no longuer maintained)
  • Remove all external content download (css, js, images)

Conclusion

I hope you’ll like it, I would understand if you say it’s not what you want to have, but I think we should do this :slight_smile: