[Koha] Screenshots internationalization for the manual (and acceptance tests?)

[Eric Bégin]

Good morning all !

For me, having the screenshots in the correct language is quite important.

However, having the screenshots updated every release is not necessary.  
For example, I don't mind if there is a slight difference in the 
screenshot when that difference is not related to the explained feature.

Don't get me wrong, I love the idea of automating the screenshots and 
the possibilities it offers, but I believe that a lot of them will need 
to be edited afterward in order to be cropped, added overlay, and so on, 
which make the automation less appealing.  I also think that it will be 
a nightmare to maintain in the long run and making the documentation 
process even harder.

The option is to generate the screenshots when we can.  Its a long 
process at first, but any body are able to take a screenshot, without 
having to code anything, which is, in my opinion, a big advantage.

My 164 Satochis ($0.02) on this sunday morning :)

Eric

On 2018-01-19 11:29, Jonathan Druart wrote:
> Hello everybody,
>
> I have spent (too much) time trying to automatically generate the
> screenshots of the manual.
> The idea behind that was multiple: keep the screenshots up-to-date from one
> version of Koha to the others, and generate screenshots in each language of
> the manual.
> I was really excited after the first half hour when I successfully took my
> first screenshot with only few lines of code.
> But after a couple of days I realize that the task is very huge: we have
> more than 1300 images in the manual, and I have generated only 68 so far.
>
> First I need to know how important is that for you. Will it really change
> our lives to have screenshots translated in other languages (and kept in
> sync with the interface)? How important is the value added?
> One thing is sure: if someone wants to translate screenshots, they should
> do it in a generic way so all languages can take advantage of it.
>
> The hidden added value of such mechanism is to add a huge test coverage: we
> are going to make sure the screenshots can be generated in several
> languages, catching issues we do not cover in our test suites, etc.
> A bit of technique: the screenshots are taken using Selenium tests (which
> we already use a bit in the test suites): it simulates a user's interaction
> with the interface.
>
> The big problem is that, for now, only developers could help me.
> But do not stop reading now please :)
>
> The code looks like that:
> C4::Context->set_preference('SpecifyReturnDate', 1);
> $driver->get($base_url.'circ/returns.pl');
> screenshot("SpecifyReturnDate", { class => "yui-u first" });
> For the "SpecifyReturnDate" screenshot, we set the syspref to 1, hit
> returns.pl and create a screenshot from the element with a class "yui-u
> first" (yes the element should have an id).
> As you can imagine this one is part of the easiest ones.
>
> Now imagine "FineNotifyAtCheckin", we want to capture the alert box when
> the patron has fines and returns an item.
> The code is:
> C4::Context->set_preference('FineNotifyAtCheckin', 1);
> my $b = Koha::Items->find(74)->barcode;
> issue( $patron, $b );
> Koha::Account::Line->new({ borrowernumber => $patron->borrowernumber,
> accountno => 1, amountoutstanding => 5 })->store;
> checkin( $b );
> screenshot("FineNotifyAtCheckin", { class => "dialog alert" } );
> Koha::Account::Lines->search({ borrowernumber => $patron->borrowernumber
> })->delete;
> First I assume I have an item with itemnumber=74 that can be issued by a
> given patron. I check it out and create a fine of 5. I check the item in
> and tadaaa I can take the screenshot for the alert dialog. Then I clean up.
>
> And trust me, this is not the hardest.
>
> So what I suggest is that, if (and only if) people are very interested in
> contributing to translate the screenshots and in the concept of having the
> whole interface tested, we could offer an easy way to contribute to this
> project.
>
> We could do that using Cucumber (see also bug 13849), and let people write
> something much more readable (by anybody), like:
> Scenario: Take a screenshot for SpecifyReturnDate
> Given I have set the syspref SpecifyReturnDate to 1
> And I hit the circ/returns.pl
> Then I take a screenshot of the element with the class "yui-u first"
>
> Or:
> Scenario: Take a screenshot for FineNotifyAtCheckin
> Given I have set the syspref FineNotifyAtCheckin to 1
> And I checked an item out to a patron
> And I added a fine of 5 to the patron
> And I checked the item in
> Then I take a screenshot of the element with the class "dialog alert"
>
> Does it seem more readable?
>
> Let me know what do you think of that and if you are willing to help.
> Then I will see if I can dedicate more time to this project.
>
> Cheers,
> Jonathan
>
> Additional information:
> - For now only sample data from "en" are used. Part of the interface is not
> translated yet (item types, authorised values, framework, etc.)
> - The process does not finish for "fr" because of bug 20043
> - I have already found several bugs (not reported yet) writing these tests.
> - The screenshots I generated are from the installer (all of them) and the
> administration part (~50%)
> - Currently I cannot regenerate only 1 screenshot (if something went wrong
> for instance). They should be independent (unless for the installer part)
> and the script should take an image name in parameter (like perl
> generate_screenshot.pl --name FineNotifyAtCheckin --lang es).
> - Could be done later:
> * Generate screenshots for "fr" with UNIMARC data
> * Use sample data from the language we want
> * Have separate data set depending on the language (like having the biblio
> titles or patron names depending on the region: John Doe for 'en', Jean
> Dupont for 'fr', Juan Pérez for 'es', etc.)
> * And certainly much more...
> The links to what have been done so far: (manual with only the installer
> and administration sections, these links are temporary)
> ar - http://download.koha-community.org/manual/wip_screenshots/ar/html/
> en - http://download.koha-community.org/manual/wip_screenshots/en/html/
> es - http://download.koha-community.org/manual/wip_screenshots/es/html/
> it - http://download.koha-community.org/manual/wip_screenshots/it/html/
> pt_BR -
> http://download.koha-community.org/manual/wip_screenshots/pt_BR/html/
> zh_TW -
> http://download.koha-community.org/manual/wip_screenshots/zh_TW/html/
>
> Here is the list of the images that have been generated:
> https://pastebin.com/RQV35cu2
> _______________________________________________
> Koha mailing list  http://koha-community.org
> Koha at lists.katipo.co.nz
> https://lists.katipo.co.nz/mailman/listinfo/koha

-- 
Eric Bégin

Tél.  : 888 604-2627
Cell. : 514 777-6572
Eric.Begin at inLibro.com <mailto:Eric.Begin at inLibro.com>

inLibro | Spécialistes en technologies documentaires | www.inLibro.com 
<http://www.inLibro.com>