Shaarli: Documentation in French

[llune]

J'envisage de commencer à traduire la documentation de Shaarli en français parce que je n'ai pas trouvé.

Avant de le faire, je préfère demander s'il y a un déjà un travail qui a commencé là dessus.

[ArthurHoaro]

Non, il n'y a aucun travail en ce sens à ma connaissance.

However having a documentation in multiple languages seems hard to maintain.

[nodiscc]

It will be hard to keep the localized documentation up to date.

I suggested something similar in https://github.com/go-gitea/gitea/issues/6552 and it seems there is no simple way to maintain docs in multiple languages (note that gitea uses Hugo for their documentation, which has built-in i18n/l10n features, but even then, keeping multiple languages in sync is painful)

[llune]

OK, I understand. You're both right! I might make one unofficial documentation though one day because we are using Shaarli at work and it would be nice to have a documentation in French. If I do, I'll let you know :)

[nodiscc]

@llune I assume you would want to _only_ translate end-user documentation? Eg. not the entire setup/admin/dev documentation, but only the Usage part?

If that's the case, that would be more manageable. since these pages don't change so often, and are the only pages of direct value to non-technical end users:

• https://shaarli.readthedocs.io/en/latest/Browsing-and-searching/
• https://shaarli.readthedocs.io/en/latest/Sharing-content/
• https://shaarli.readthedocs.io/en/latest/RSS-feeds/

What could be done:

• Create pages $pagename.fr.md in https://github.com/shaarli/Shaarli/tree/master/doc/md named after the english page.
• Translate these pages to French
• Add a banner on top of each page:

| 💥 | La documentation en français peut avoir un léger retard sur la [documentation officielle en anglais]($pagename.md). |
|---------|---------|

• We add a simple Language: [EN]($pagename.md)|[FR]($pagename.fr.md) switch to each affected page.
• You subscribe to https://github.com/shaarli/Shaarli/commits/master/doc/md.atom to watch for changes to english docs, and help us maintain the docs in french :) That is actually the hard part.

Does this make sense? Please let us know if you're interested, feel free to re-close if not.

[virtualtam]

Hi,

Documentation in multiple languages can be managed using the Sphinx documentation engine, which provides internationalization features:

• https://www.sphinx-doc.org/en/master/usage/advanced/intl.html
• https://www.slideshare.net/streetcleaner/writing-multi-language-documentation-using-sphinx

The translation files use the Gettext format and can be edited with Poedit or sphinx-intl

As Sphinx is ReadTheDocs' canonical engine, internationalization is supported there as well:

• https://docs.readthedocs.io/en/stable/localization.html
• https://docs.readthedocs.io/en/stable/guides/manage-translations.html

This would require porting the documentation to Sphinx (which we already use for the Python API client) and either switching to CommonMark (Markdown with batteries included) or reStructuredText.

IMO this would be interesting as Sphinx has a number of advantages over MkDocs:

• syntax checks (typos, dead internal links/references)
• tooling (Makefile, Tox)
• flexible table of contents management
• integrations with diagramming tools like Graphviz/dot and PlantUML
• builders for HTML, LaTeX, PDF, EPUB, etc.

[llune]

Hi!

I've not forgotten you but had no time to work on it. If I do work on the documentation, I'll let you now before I start!

[nodiscc]

The switch to recommonmark + sphinx can easily be done, here is a sample working config:

• https://gitlab.com/nodiscc/debian-live-config/-/blob/master/Makefile#L107
• https://gitlab.com/nodiscc/debian-live-config/-/blob/master/doc/md/conf.py
• https://gitlab.com/nodiscc/debian-live-config/-/blob/master/.readthedocs.yml

Edit: issue about switching doc generation system in https://github.com/shaarli/Shaarli/issues/1451