[Weblate] Re: Using Weblate to translate documentation (with Docusaurus?)
Le 28/03/2020 à 15:23, Antonin Delpeuch (lists) a écrit : > Building a system like yours could be an option, but of course it would > be even better if that was supported natively by Weblate. I don't expect Weblate to cover such use case. Internationalization is really tight to the technologies used to create content and the processes between creators and translators. Here this system only works for Antora and the way Fedora decided to organize its repositories (to match translators processes). If Weblate comes with a markdown support, I bet this will suit a simplistic workflow, and never will we suited for publication automation. You'll always have to put the glue between your publication system, your way of handling source code, your translations process and your automation system. The biggest issue with websites generators and web tools, is that most of them never really though on how to answer localization questions. Hugo did this effort, and I documented it here: https://jibecfed.fedorapeople.org/blog-hugo/en/2018/11/building-a-multilingual-static-website-with-hugo/ Last time I looked at it, Jekyll provided no similar feature (same as Antora). -- Jean-Baptiste Holcroft ___ Weblate mailing list -- weblate@lists.cihar.com To unsubscribe send an email to weblate-le...@lists.cihar.com
[Weblate] Re: Using Weblate to translate documentation (with Docusaurus?)
On 28/03/2020 15:10, Jean-Baptiste wrote: > > If you want to see the result, here are some statistics: > https://docs.stg.fedoraproject.org/en-US/docs-l10n/ > > If you want the explanation on how it works: > https://github.com/asciidoctor/docs.asciidoctor.org/issues/19 > > I really recommend to give a try to asciidoc for documentation and > internationalization. > It looks great indeed. Building a system like yours could be an option, but of course it would be even better if that was supported natively by Weblate. Cheers, Antonin ___ Weblate mailing list -- weblate@lists.cihar.com To unsubscribe send an email to weblate-le...@lists.cihar.com
[Weblate] Re: Using Weblate to translate documentation (with Docusaurus?)
Le 20/03/2020 à 15:44, Antonin Delpeuch (lists) a écrit : >> Fedora is using some more complex tooling for the docs, see >> https://fedoraproject.org/wiki/User:Jibecfed/fedoradoc-antora-localization > Those pointers are super useful, thanks! If you want to see the result, here are some statistics: https://docs.stg.fedoraproject.org/en-US/docs-l10n/ If you want the explanation on how it works: https://github.com/asciidoctor/docs.asciidoctor.org/issues/19 I really recommend to give a try to asciidoc for documentation and internationalization. -- Jean-Baptiste Holcroft ___ Weblate mailing list -- weblate@lists.cihar.com To unsubscribe send an email to weblate-le...@lists.cihar.com
[Weblate] Re: Using Weblate to translate documentation (with Docusaurus?)
On 26/03/2020 15:20, Michal Čihař via Weblate wrote > > It's quite likely that Weblate will have native Markdown support soon > (see other thread), so maybe the best approach is to wait for it :-). > That would be amazing! I have added a bounty on this issue: https://github.com/WeblateOrg/weblate/issues/3106 Antonin ___ Weblate mailing list -- weblate@lists.cihar.com To unsubscribe send an email to weblate-le...@lists.cihar.com
[Weblate] Re: Using Weblate to translate documentation (with Docusaurus?)
Hi Antonin Delpeuch (lists) píše v Pá 20. 03. 2020 v 15:44 +0100: > If we wanted to use Weblate in place of Crowdin, it seems to me that > we > would need to introduce a piece of software in between: something > that > takes markdown files, breaks them down into translatable units which > would be stored in some standard format (say a POT for gettext), and > be > then able to build translated versions of these markdown files using > the > gettext PO files (and the original markdown). It's quite likely that Weblate will have native Markdown support soon (see other thread), so maybe the best approach is to wait for it :-). > For instance: > https://po4a.org/man/man7/po4a.7.php I'm using po4a for some documents localization and it works reasonably well (it's used on https://hosted.weblate.org/projects/gammu/gammu-docs/). -- Michal Čihař | https://cihar.com/ | https://weblate.org/ ___ Weblate mailing list -- weblate@lists.cihar.com To unsubscribe send an email to weblate-le...@lists.cihar.com
[Weblate] Re: Using Weblate to translate documentation (with Docusaurus?)
Hi Michal, Thanks for the lightning-fast reply! On 20/03/2020 14:00, Michal Čihař via Weblate wrote: > I know projects translating Sphinx or Publican based docs in Weblate: > > * https://docs.godotengine.org/en/stable/ > * https://docs.phpmyadmin.net/en/latest/ > * https://debian-handbook.info/ > > Fedora is using some more complex tooling for the docs, see > https://fedoraproject.org/wiki/User:Jibecfed/fedoradoc-antora-localization Those pointers are super useful, thanks! > >> We have identifier Docusaurus [2] as a potential good candidate to >> generate our docs, which comes with an integration with Crowdin for >> translation. I wonder if anyone has tried to use Weblate with >> Docusaurus? Interoperability with other translation systems seems to >> be >> on their roadmap for their v2 [3], but it does not seem to be usable >> yet, so I wonder if anyone has experience with setting that up. > > No experience with that, do you know how it stores the translations? I > hope they did choose some standard format for that and in that case it > would be easy to use with Weblate :-). > Crowdin seems to have a very different architecture: translations are not stored on the repository being translated. Instead, translations are stored in Crowdin itself, and one needs to retrieve the translated files at build time. For instance, say you have a Jekyll site with a bunch of Markdown files that you want to translate, you would change the build process (the step where you invoke Jekyll) to also: - push your markdown files to Crowdin (letting it know what has been updated and should be translated); - pull the translations frow Crowdin, returned as Markdown files themselves; - let Jekyll build the site as usual (it does not need to be aware that some of these files are translations of others). This CircleCI workflow seems to summarize the process pretty well: https://docusaurus.io/docs/en/translation#automated-file-sync-using-circleci With this architecture, I am obviously concerned about vendor lock-in (especially since Crowdin is not FOSS), lack of versioning and keeping track of translation authorship in the version control system. If we wanted to use Weblate in place of Crowdin, it seems to me that we would need to introduce a piece of software in between: something that takes markdown files, breaks them down into translatable units which would be stored in some standard format (say a POT for gettext), and be then able to build translated versions of these markdown files using the gettext PO files (and the original markdown). For instance: https://po4a.org/man/man7/po4a.7.php https://www.npmjs.com/package/gettext-markdown Would you recommend any of these? Best, Antonin ___ Weblate mailing list -- weblate@lists.cihar.com To unsubscribe send an email to weblate-le...@lists.cihar.com
[Weblate] Re: Using Weblate to translate documentation (with Docusaurus?)
Hi Antonin Delpeuch (lists) píše v Pá 20. 03. 2020 v 13:23 +: > > We use Weblate to translate OpenRefine's UI and we are very happy > with > it. [1] > > We are considering revamping our documentation and make it > translatable > too. Therefore, we wonder: could Weblate be also used to translate > docs? > Which documentation generators is it know to work well with? I know projects translating Sphinx or Publican based docs in Weblate: * https://docs.godotengine.org/en/stable/ * https://docs.phpmyadmin.net/en/latest/ * https://debian-handbook.info/ Fedora is using some more complex tooling for the docs, see https://fedoraproject.org/wiki/User:Jibecfed/fedoradoc-antora-localization > We have identifier Docusaurus [2] as a potential good candidate to > generate our docs, which comes with an integration with Crowdin for > translation. I wonder if anyone has tried to use Weblate with > Docusaurus? Interoperability with other translation systems seems to > be > on their roadmap for their v2 [3], but it does not seem to be usable > yet, so I wonder if anyone has experience with setting that up. No experience with that, do you know how it stores the translations? I hope they did choose some standard format for that and in that case it would be easy to use with Weblate :-). Best regards -- Michal Čihař | https://cihar.com/ | https://weblate.org/ ___ Weblate mailing list -- weblate@lists.cihar.com To unsubscribe send an email to weblate-le...@lists.cihar.com
