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

Tue Jan 23 03:01:23 NZDT 2018

Hi Éric,

The screenshot are automatically cropped, did you watch at the examples I
generated?
For each screenshots it retrieves the positions of a list of elements, so
no need to maintain or keep them up-to-date, we just need to keep the same
elements on the pages (id or class). It is the same problem of any selenium
scripts.

As I said, if you generate 1 screenshot in a generic way, it will be kept
up-to-date and for all languages. If you generate it manually, it will not.
I am sure it is less time consuming to write the 5 lines of code than take
and crop a screenshot for the 9 languages we generate the manual.

Cheers,
Jonathan

On Sun, 21 Jan 2018 at 10:37 Eric Bégin <eric.begin at inlibro.com> wrote:

> 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>
> _______________________________________________
> Koha mailing list  http://koha-community.org
> Koha at lists.katipo.co.nz
> https://lists.katipo.co.nz/mailman/listinfo/koha
>