Request for Comments - Where to translate the new project site (and maybe all strings in the future?)

Hi there. What feels like several millennia ago, I proposed our next iteration of our website, wiki, FAQ, install guides, and whatnot. This project is still ongoing, but we’re finally at a stage where we pretty much “just” have to push contents in and publish it.

One thing that came up early in the development was the need to have parts of the site potentially translatable to give more people a chance to understand what we’re all about.

Currently, diaspora* is using WebTranslateIt to localize texts, and while I really do appreciate their support in all the years, that’s not a possibility for the project site - both for technical reasons, as well as due to strong concerns about the translator’s UX.

Initially, I made the decision to build the prototype based on Transifex, a commercial service that offers a web-based community-translation service, while having the benefit of enabling easy purchase of commercial translation services if needed. While their prices are way too high for most projects, they do have an Open Source Support program, and they agreed on hosting diaspora* with no limitations on words, strings, projects, or collaborators.

More recently, however, Weblate came to my attention. Weblate is an Open Source product, funded by hosted offerings and paid support. It’s used by a lot of FOSS projects, like the Godot game engine, OsmAnd, and insporation*. We could, in theory, use their hosted offering, or we could even set up our own instance as a central place for all diaspora*-related translations.

And this is where your feedback is requested, because I actually don’t know what to do.

As you may know, the new project site is based on a custom file format, which is a combination of Markdown (the kramdown dialect) as well as ERB for server-side templating and variables/partials. If you don’t know what I’m talking about, here is the code for what will eventually become the front page, and here is the code for one step of the new installation guides which shows off the use of variables and server-side logic.

Transifex handles markdown files very nicely. It’s splitting the entire file into sections that can be translated/reviewed/invalidated individually, and it’s even splitting the front matter into individual strings that can be translated without having to be careful about the keys. Here’s what the front-page example looks like in Transifex:

Weblate, on the other hand, has no understanding of markdown whatsoever. While there is a feature request open for a while, it’s clear that this is no easy task, and it might not be there for a long time. In Weblate’s UI, translating the same page would have to be done in one large text box, with no real help or UI candy:

So, now I’m at the point where I’m not sure what to do. We could either go the idealistic route and use Weblate just because it’s a FOSS project and taking hits in some UX/UI areas. Or we could go the more pragmatic route and use Transifex for their superior UI/UX, while acknowledging that we create a new dependency on a commercial service that does not allow us to customize anything at all.

What’s your opinion here?

(Keep in mind that, even though this discussion currently only affects the new project site, it’s not totally inconceivable that we’ll move the diaspora* strings to the same platform at some point in the future, to make management and contributor directions a lot easier.)

I can’t say I have a strong preference. Just to throw more options on the table, the po4a tool linked in the weblate issue looks like an interesting option too. For better or worse it would be splitting up each paragraph into its own key.

To me Transifex looks like the much better UX for potential translators and less chance to break because of syntax errors, if every section is translated separately. If we translate a complete file like on your weblate screenshot, we could also just do translations using GitHub PRs.

But otherwise I think I don’t have much to say about this topic, just a few thoughts, no strong opinion.

Played around with that, and while it works, I like that even less: Now all paragraphs are just thrown together, and it’s not super obvious which sections belong together :confused:

Thanks for your feedback so far. Since Transifex support is already implemented, I’ll leave that be for now, unless there are new and different opinions raised here. :slight_smile:

I don’t think I can add anything useful. I’ll leave it up to you – I’m sure that between you you’ll identify the best option.

I am active in a few opensource projects and they mostly use transifex for translation and readthedocs.org for documentation.
If you use github for your documentation files, you can make language branches for translations as .rst files