Book for Ukraine

An open-source implementation of the Czech-Ukrainian book for children, Povídání modro-žluté krajiny.

The book has been succesfully crowdfunded and is now available! The web version is available (in 🇨🇿 and 🇺🇦) to browse for free: https://ukrajinskaknizka.cz

Please, do get in touch (create an issue!) if you'd like to collaborate on this project in any way, e.g.:

• it would be great to support more languages – help translate and/or record in(to) your native language,
• implement any of the fixes or features mentioned below or in Issues.

In short, all forms of contribution are welcome :) Most importantly, please do share the website with anyone who might find it useful or enjoyable.

And more generally, feel free to adapt this project to implement any other web-based book with playable text recordings. Ideally, this project would be decoupled from the assets and serve as a general-purpose web-audio-book toolkit but there hasn't been enough time for that yet.

Languages

We treat the website languages separately from the book languages for multiple reasons.

The book texts require fine-grained translations and human-defined typesetting.

Currently, the following languages are supported:

Language	Website	Book Texts	Book Audio
🇨🇿 Čeština	✔	✔	✔
🇺🇦 Українська	✔	✔	✔
🇬🇧 English	✔	❌	❌

TODO

We're slowly moving these into proper Issues.

Settings

• Playback speed
• Playback volume
• Wait time between paragraphs/pages when autoplaying (see Reading flow)
• Persist/cache settings (states in general, including things like locale)
  • I guess this would require annoying cookie prompts, though? :(
• Allow alphabet conversions (transliteration)
  • Implemented for the book texts (poems) which should be enough

Reading flow

• Pagination, page jumping
• Autoplay
  • Play the following recordings in one page that follow the selected text implicitly
    • Implemented but currently disabled because it's not very user-friendly, waiting for improvements there
  • One page in one or both languages (play in a circle, not just till the implicitly last one)
  • Across pages, with smooth jumps
• Scroll/zoom to the current image/text when autoplaying

Presentation

• Better UI in general (navbar, ...)
  • Now make it even better
    • Fine for now, I guess?
• Equalise volume across languages (for example, cs is currently louder than ua)
• Inform about landscape mode on mobile
  • Solved by displaying single pages on mobile and two facing pages on desktop
• Object animations
  • Simple wiggle on hover/click
  • Temporarily animate/pop text and image to foreground
• Cursor pointer on clickable text/images
• Also play the text in a selected language on image click in addition to text click
• Playing indicator
  • Currently, text is slightly enlarged, is there anything better?
• Story order indicator

Languages

• Generalise the website into multiple localisations (info/settings/... – not the actual book texts)
  • Try to load user's locale by default
• Instead of arbitrary ordering, always select just two languages (and thus get their order implicitly)
• The following are probably out of scope (user can just use their device to translate/play text in(to) whatever language they please):
  • Auto translation into unsupported languages
  • Auto TTS of languages without audio recordings

Loading times

• Optimise sizes of:
  • Images
  • Audio
  • Other resources (JSON files, ...)

SEO optimalisation

• <meta name="..." content="...">

Tech debt

• Proper typescriptification, including introducing types for the data structures loaded from jsons
  • This would be very helpful for development as it would give us type hints among many other things
  • Done at least partially for our custom types, no idea if it's proper in any way :)

Fixed issues

• Align texts according to the typeset version.
• z-index issue
  • Nevermind, z-index worked, but only non-negative values
  • Background now sometimes covers objects (rainbow cloud)
  • Text should be in the foreground (above objects)
  • Simply setting z-index doesn't seem to help :(
• Overflow (duha) when viewing two pages, but don't overflow in the single page view
• Add a license (dual, MIT for code, copyright for assets)
• Properly load and use the correct (Ubuntu) font.
  • Temporarily using Open Sans instead as it's variable and can animate font weight (until we have another playing indicator)

Webdevlog

2022-06-07

Moving the entire webapp to SvelteKit.

2022-05-23

Thanks to the kind colleagues in Medallia's Prague branch, we now have a proper 🇺🇦 translation of the website :)

2022-05-22

I've shared the website in a couple of (semi-)public places and forums, including a reddit post about the book as a Svelte project.

Still, there hasn't been much traffic yet (58 website visits (according to 🐐) and 4 GitHub ⭐ so far) and noone has yet offered to help with the Ukranian website translation.

2022-05-20

I've added at least machine translations to Ukraine for the website. Let's finally share the website to get some help and feedback :)

2022-05-19

Another major rework, this time I've added localisation support and translated the website to English.

I think the website is now ready to be pre-released (i.e., released as a preview for testing purposes) – I've really wanted to add at least English support in order to not put everyone off immediately.

2022-05-16

A ton of little but impactful improvements, the website may now be actually nice and pleasant to use. The diff speaks for itself.

The 🇨🇿 and 🇺🇦 audio files are now equalised and better cut.

One of the more interesting problems has been the rainbow cloud overflow: since the image (and this is the only one) spans two pages, it overflowed in the single-page view. However, setting overflow to hidden wasn't helping as the cloud would then be cut off in the two-pages view. I've solved the problem by dynamically computing if we see one or two columns (pages) and setting overflow based on that. Please let me know if there's a better (e.g., pure css?) solution.

The Ubuntu font is now properly used. As it doesn't support variable weights, we instead scale the currely playing text up a bit (10%).

I've made use of the Lighthouse tool to help optimise the website and find major problems.

2022-05-14

Finally, the mystery of proper text scaling has been solved! We simply dynamically check the column (page) width and set the font-size in pixels using a magic constant of almost 42.

However, this means that the text might be too small on mobile, we'll see. Either way (as expected), it's quite difficult to be properly responsive and I welcome any suggestions or other implementations.

2022-05-13

Fixed problems with computed text boxes not matching the physical (typeset) version. The problem was caused by ingesting PSD (images, background) and PDF (texts) that had different backgrounds.

The text export script now handles additional cuts (offsets) of the page.

2022-05-12

For the past couple of days, it was just refactoring and then refactoring the refactoring (and then some more).

The result is now the website looks identical, but we automatically parse all input assets (including typeset texts, audio and images) to produce the final working website (see scripts).

Also I've finally introduced at least some types and changed the object hierarchy of the main pages.json to make it easier to work with in Svelte (basically, each collection is now an array, rather than a dictionary).

2022-05-08

General effort to make the website (navigation, menu, footer) look decent and be up-to-date. More work is still necessary.

2022-05-07

Major update: I've separated foreground objects from background using a python script to export all data (image data as well as their metadata) from the original PSD file and to also combine the new objects json with the already existing pages json.

It's quick and (well, I wish it was quick, really) dirty but it makes the job done.

As a result, the background is now only loaded once (but displayed multiple times) and objects are loaded separately. The main advantage is we can now freely animate/click/... them independently.

We now also have a proper domain: https://ukrajinskaknizka.cz

Migrating with GitHub Pages was rather straightforward, it's basically just updating the CNAME.

I've registered the domain at WEDOS (Google domains unfortunately don't support the .cz TLD) and it costs cca 175 CZK per year.

2022-05-05

Added actual book images. Pages 2 and 3 now have both texts and recordings in both languages.

As one would expect, some minor tweaks had to be done to accomodate some unforeseen differences in asset formats but nothing too difficult.

Most importantly, the website is now responsive and displays single pages on smaller (mobile) devices while also seamlessly displaying the two facing pages on larger screens. Thankfully, that was extremely easy to do with the Bulma CSS framework we're using. It required basically just two lines:

• Wrap everything in multiline, gapless columns
• Wrap each (single) page in an is-half column

The biggest challenge that remains to be solved is text sizing. We want it to be both easily readable as well as reasonably responsive (perhaps scaling with the image size).

Additionally, I've only now realised that the background on all pages is identical and we could (should?) thus optimise by rendering background and foreground objects separately (only load the background once, of course).

Another nice-to-have feature might be object animations if we end up treating them as individual objects.

Early 2022

Functional website skeleton in Svelte.

The website can display arbitrary images, texts (their position is given in a JSON) and play an audio recording for each text. I'm testing it using placeholder data. We can also reorder the languages and theoretically support any number of them.

Whenever we have final assets, simply linking them should be enough to have a functional web (audio)book :)

License

See the license file.