a different approach to release announcements and translations thereof

Wed Apr 29 10:17:44 PDT 2020

Hi Peter,

I guess the process would seem very easy and natural to a developer and less easy and comfortable to someone who normally doesn't deal much with code.

The easiest way might be something like this

(a) create a GitHub account if you don't have one
(b) fork the project on GitHub (there's a button to do that when you are logged in and open https://github.com/subsurface/subsurface.github.io <https://github.com/subsurface/subsurface.github.io>
(c) clone that repo to your local system:

(this assumes a Mac or Linux - I'm sure someone else can fill in the steps for Windows)
mkdir -p ~/src
cd ~/src
git clone https://github.com/<your-account-name>/subsurface.github.io <https://github.com/%3Cyour-account-name%3E/subsurface.github.io>
cd subsurface.github.io

you have now checked out the master branch. It's typically a good idea to keep that in sync with upstream and not modify it locally.
git pull origin master
will keep it in sync.

(d) create a local branch when you start making changes
git checkout master
git pull
git checkout -b translate494 # or whatever name you want to give that branch

(e) copy the announcement you want to translate into the language folder, edit the front matter (the meta data between the two lines with dashes at the top "---") - make sure you don't change the 'ref' but do change the 'lang' tag.
(f) add the new file
git add nl/_drafts/xxxxx.MD
git commit -s -a -m "translation of ..."
git push origin translate494

(g) on the GitHub website, create a pull request

Reading this, it looks hard and scary - but it's actually just a hand full of steps, and most of them are only needed once.
And frankly, with this setup I'm equally happy if you were to simply edit the file (i.e., create a translation) and send that text to me in an email and I can take care of the mechanics.

Rest assured, this is NOT how we are going to translate the app - transifex is perfect for that. But the translation of the announcements was insanely painful for me because it involved so many manual steps that simply couldn't be automated with the tools available to me. That's why I am suggesting this change.

The design with the desktop-release-bottom.MD file is indeed a bit odd. I'll figure out how to do this in a per-language manner. The reason for the existence of this include is that this is exactly the same in every announcement (and has been for quite a while), so it seems much easier to just include the text.

Finally, the question about _posts and _drafts -- that's arbitrary. We could have the draft in the _posts folder. What makes a draft a draft is the fact that it doesn't have a date at the first part of the file name. Once we release, all I do is rename and move the files (that's a simply git operation) and push that change to the repo, then the files will automatically show up.

I'm curious what other translators think. Robert/Berthold/Stefan (German), Salva (Spanish), Pedro (Portuguese)... do we have anyone interested in doing a French translation? Any other languages I should add?

Fundamentally this is making MY life an order of magnitude easier (likely more). But if it prevents people from translating, then it isn't worth it. I can look into an easier setup for people doing translations. What OS are you running, Peter?

/D

> On Apr 28, 2020, at 10:56 PM, Peter Zaal <peter.zaal at gmail.com> wrote:
> 
> Hi Dirk,
>  
> As an active Dutch translator I am sure willing to give this a try. But not being extremely familiar with the process of submitting changes, can you give a small explanation/steps on how to do this?
> I took a look into the repo and the setup itself is quite easy to understand. I was fairly happy with translations for the website on Transifex, but if this is so painful to process and use on the final website we might try something else (or use more automation?).
> I do hope that this will only be for the website and not for all translations in the end. I feel Transifex is still a great tool for translators, very easy to use, also for non-technical people which makes it easier to step in as a translator.
>  
> The only thing I don’t really like in the repo is the desktop-release-bottom.MD include with the %if page.lang constructs. That is inconsistent with the other language folder layout, and will bloat over time with more languages. Maybe this is something you can look into, why not just a desktop-release-bottom.MD per language in the existing language folder? It does not seem like a real common file right now.
> The other that is not directly clear to me, the difference between posts and drafts. So is there is process that promotes a draft to a post? Why can a new announcement not already be in the _posts folder?
>  
> Peter
>  
> Van: subsurface <subsurface-bounces at subsurface-divelog.org> Namens Dirk Hohndel via subsurface
> Verzonden: dinsdag 28 april 2020 23:39
> Aan: Subsurface Mailing List <subsurface at subsurface-divelog.org>
> Onderwerp: a different approach to release announcements and translations thereof
>  
>  
> For the last few releases I have struggled with the convoluted infrastructure (which, of course, I have created - so this is all my fault) for publishing announcements. WordPress had to be hidden from the world (as we had way too many hacking attempts and the amount of time spent on keeping this secure and alive was ridiculous), the static export is nice but takes many manual steps and is pretty error prone. And the integration with transifex for translations was just painful for everyone involved (especially me).
>  
> Based on this. I am once again going to try something different. Something that's completely integrated with GitHub and should in theory make it easy for people to translate announcements and maybe even take over some of the maintenance work from me. Because that's one of the oddities here; several people over the years have offered to help -- but my setup just wasn't done in a way where it felt easy to give others access...
>  
> As a result, we now have a GitHub.com/subsurface/ <http://github.com/subsurface/>subsurface.github.io/ <http://subsurface.github.io/> repo which then gets published as https://subsurface.github.io/ <https://subsurface.github.io/> via GitHub pages. If this works out, this can apparently be reasonably easily integrated with our custom domain.
>  
> The goal right now is NOT to reproduce our website there. Instead I was hoping to just move our announcements to that URL and allow people to translate the through a simple pull request. If this turns out to be amazing and everyone loves it, then we can think about migrating (most of) the full website, but for now I wanted to focus on the announcements.
>  
> Posts are written in markdown - just like our README. And typically styling for announcements is so primitive that the syntax really shouldn't matter all that much. I have re-created the Subsurface 4.9.3 announcement and created a Subsurface-mobile 3.0 announcement (which had never been published anywhere) and have also added a draft for Subsurface 4.9.4. So far I have only populated a bare basics German translation (that needs a lot more work), and haven't populated any of the other translations, yet. But I think that the structure is pretty straight forward and should make it easy for others to step in and complete my work. 
>  
> - there's a shared footer for desktop release announcements (aptly named _includes/desktop-release-bottom.MD) that tells people how to download binaries. I have this in three languages and it should be obvious how to add others. The use of variables like {{page.version}} should be quite easy to understand.
> - posts are in subdirectories, currently we have en/ and de/, filenames are iso-date plus topic, translations are connected via a 'ref' tag in the front matter (for simplicity I tried to keep this very structured, e.g. subsurface-4.9.3).
> - some terms have central translations (this includes the language short codes, names, and flags) in _config.yml, but in general most of the translation work likely consists of copying the English post into the right directory, keeping the ref in the front matter and translating the actual announcement text
>  
> Maybe I'm underestimating the learning curve, but I'd love to hear what people think - and ideally some of you would try to add our most common translations (Dutch, Spanish, Portuguese - for those I have created languages, if you want to add a different one, you'll need to add another language block in _config.yml).
>  
> Thanks
>  
> /D

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.subsurface-divelog.org/pipermail/subsurface/attachments/20200429/89f4e2fa/attachment.html>