Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Switch to sphinx to be able to translate documentation #98

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

clrh
Copy link

@clrh clrh commented Jun 28, 2021

We needed to translate in french the Omeka S's documentation, and mkdocs
does not fit our needs. Sphinx provides by default all the tools needed
to translate with PO files and generate translated documentation. The
generated documentation is the same as if it was generated by mkdocs.

Ideally, we think that all the PO files should be in the official
documentation repository, and they could be modified on Transifex, so
that anyone can participate to translation.

Instructions for translating are written inside translation.md

@jajm
Copy link

jajm commented Jun 28, 2021

FYI, french translation has started on https://github.com/biblibre/omeka-s-enduser-fr (on master branch) and is publicly available here: https://omeka-s-enduser-fr.readthedocs.io

@clrh
Copy link
Author

clrh commented Jul 13, 2021

To be complete, we did a communication we did to the French community (in French too).

Regards.

@jajm jajm force-pushed the sphinx branch 2 times, most recently from 799e6a4 to 425127d Compare October 5, 2021 09:04
@jajm jajm force-pushed the sphinx branch 3 times, most recently from aabd312 to d15c25e Compare June 27, 2022 09:23
@clrh
Copy link
Author

clrh commented Jun 28, 2022

Hi,

We would like to have some feedbacks. Please have a look, it would be a real gain for Omeka community who are not English talking people ;).

Thanks.

@zerocrates
Copy link
Member

Hi,

This one is complicated for us, since we'd have to change the server-side systems used to build and deploy the docs, as well as the local setups for people working on them. We've also got several other mkdocs projects so it's convenient for us to have the same setup for multiple things.

What in particular does Sphinx provide here that mkdocs doesn't? A system that generates gettext files from the source docs? I'm not really familiar with how localization/translation works in Sphinx.

@jajm
Copy link

jajm commented Jul 29, 2022

Hi,

I understand that changing tools is complicated, but I believe having documentation translated in other languages would really benefit Omeka and its users.

What in particular does Sphinx provide here that mkdocs doesn't? A system that generates gettext files from the source docs?

Yes. And a system that generates translated documentation using these gettext files. You can see the basic steps in the translation.md file included in this pull request.
And readthedocs supports multi-language documentation with sphinx (example: https://omeka-s-module-search.readthedocs.io/en/latest/, https://omeka-s-module-search.readthedocs.io/fr/latest/

The last time I checked, MkDocs supported translations only for the theme, not for the documentation itself

We needed to translate in french the Omeka S's documentation, and mkdocs
does not fit our needs. Sphinx provides by default all the tools needed
to translate with PO files and generate translated documentation. The
generated documentation is the same as if it was generated by mkdocs.

Ideally, we think that all the PO files should be in the official
documentation repository, and they could be modified on Transifex, so
that anyone can participate to translation.

Instructions for translating are written inside translation.md
It is a syntax extension that is not supported by MyST

Instead, add a line of javascript to add this attribute to all
<a> elements that have the `external` class. This class is added by
sphinx automatically
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants