You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
While it's true that CKAN is already used across the world, I think we should aim to have a user base which is as large and diverse as possible. One potential barrier for adoption, specially in the Global South and among small organizations, is having the documentation in English only. We do have a fantastic community of translators that provides the CKAN interface in multiple languages so perhaps we can set up a system that allows local communities to contribute translations for the documentation or parts of it. OKF can help coordinate a team led by @aivuk that might be able to kick start a Brazilian Portuguese translation and potentially other groups in Latin American for a Spanish translation.
Of course translating documentation comes with an extra set of challenges:
Size: we have a lot of docs! It's unlikely that the whole of the documentation can be translated in one go, so we should allow for partial translations (selected pages) and falling back to the English version for untranslated pages (Maybe with a noticed on top saying in the relevant language ("This page is not yet translated. Want to help?")
Keeping it up to date: documentation is code, and we keep ours close to the source code and tied to a particular CKAN version. We update the documentation regularly, and these changes should be ported to any translation.Translations should keep up to date but that of course will depend on each translation team availability. Perhaps translated extensions should include notices stating that these are community-led efforts and might be out of date.
Maintenance burden: after much fiddling we've reached a setup where our docs are transparently updated after merging changes to the main repo. Ideally, translations should not involve extra work from the Tech Team other than initial setup of a language. Translated docs should be maintained by their own communities
There are different approaches followed for supporting different locales for documentation. Projects like FastAPI keep all translations in the same repository, while others like Django use separate repositories and Transifex.
For a first pilot, I think it would be good to stick to the tools that we use now, namely Read the Docs. Their multilingual support boils down to essentially having one parent project (the current CKAN docs) and multiple separate projects (eg ckan-pt.readthedocs.io) which are marked as translations of the parent one. While projects need to be separated on Transifex that doesn't mean that the sources need to be separated, we could either ask translations maintainers to fork the main ckan repo and build their RTD projects from there, or keep all translations in the main repo (either translated .rst files or potentially with po files) and build separate RTD projects from the same source.
I'm leaning towards keeping it separate at least for now until we test the process and see what it actually involves, but I'm keen on hearing people's thoughts.
Does anyone have experience managing translated documentation for open source projects or similar setups?
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
-
While it's true that CKAN is already used across the world, I think we should aim to have a user base which is as large and diverse as possible. One potential barrier for adoption, specially in the Global South and among small organizations, is having the documentation in English only. We do have a fantastic community of translators that provides the CKAN interface in multiple languages so perhaps we can set up a system that allows local communities to contribute translations for the documentation or parts of it. OKF can help coordinate a team led by @aivuk that might be able to kick start a Brazilian Portuguese translation and potentially other groups in Latin American for a Spanish translation.
Of course translating documentation comes with an extra set of challenges:
There are different approaches followed for supporting different locales for documentation. Projects like FastAPI keep all translations in the same repository, while others like Django use separate repositories and Transifex.
For a first pilot, I think it would be good to stick to the tools that we use now, namely Read the Docs. Their multilingual support boils down to essentially having one parent project (the current CKAN docs) and multiple separate projects (eg ckan-pt.readthedocs.io) which are marked as translations of the parent one. While projects need to be separated on Transifex that doesn't mean that the sources need to be separated, we could either ask translations maintainers to fork the main ckan repo and build their RTD projects from there, or keep all translations in the main repo (either translated .rst files or potentially with po files) and build separate RTD projects from the same source.
I'm leaning towards keeping it separate at least for now until we test the process and see what it actually involves, but I'm keen on hearing people's thoughts.
Does anyone have experience managing translated documentation for open source projects or similar setups?
Beta Was this translation helpful? Give feedback.
All reactions