[DOCS] Explain Parsons and how to translate them on Weblate

[Felienne]

Add Parsons and Quiz to wiki. Making an issue so we don't forget, the discussion can be archived now.

Discussed in https://github.com/hedyorg/hedy/discussions/4509

^{Originally posted by **yilmazdurmaz** September 19, 2023} This is for translation contributors. Parsons are a puzzle game where the lines of codes are scrambled and students need to reorder them correctly. There are two string items to translate in the Weblate component: explanation of what the code does once it is in order, and a complete ordered code. the explanation mainly consists of statements with each on their own lines (there might be an extra paragraph for introduction): > You're a customer at bakery Hedy. > You walk into the bakery and are welcomed by the baker. > He asks what type of pie you want to order. > Then he repeats your answer back to you. > Lastly, your order is being prepared. Translate them line-by-line as they are a series of instructions to follow. the code has a few lines with each keyword in curly braces: ``` {print} Welcome to bakery Hedy! {ask} What type of pie do you want to order? {echo} So you want {print} Your order is being prepared! ``` *Do not translate* the keywords in the braces. They are replaced automatically by the keywords translated in the "Weblate > Hedy > Keywords" component. The following is one translation for Turkish. ``` {print} Hedy fırınına hoş geldiniz! {ask} Ne tür bir turta sipariş etmek istersiniz? {echo} Yani istediğiniz {print} Siparişiniz hazırlanıyor! ``` For non-programmer translators, translating the code will be a heavy work. You need to identify correct parts of the code where the words must not be translated or change its shape and where expressions must be switched a bit. There are times curly braces are forgotten in the source material. consider this (I deliberately removed braces): ``` toy {is} ask What would you like to buy? print toy is added to your shopping cart. ``` "toy" is a variable name, "is/ask/print" are keywords. you need to recognize and treat them for what they are, the keywords. One easy way to translate programming codes is then to first use them in English while translating the other parts. And then translate these too. step-1 : identify keywords and keep them as is. do not change the main structure ``` toy is ask Ne satın almak istersiniz? print toy alışveriş sepetinize eklendi. ``` step-2: translate identified variable names; but for keywords use translated keywords only when curly braces are forgotten. ``` oyuncak {is} sor Ne satın almak istersiniz? yazdır oyuncak alışveriş sepetinize eklendi. ```` "is" already in braces, so no change. "ask/print" are keywords but braces forgotten, use translated keyword. "toy" is variable name, replaced with name following programming naming rules. PS: These same code conversion rules applies to other parts as well; Adventures are the largest part that needs this attention. PS: I have attention problems, so this is as far I can go. Let's extend it with Q&A and make a better translation-contributors help page.

[Felienne]

"is" already in braces, so no change. "ask/print" are keywords but braces forgotten, use translated keyword. "toy" is variable name, replaced with name following programming naming rules.

Hi @yilmazdurmaz!

This is actually not correct, if braces are forgotten, best if that you still use {print} in your translation, and also change this in English. Otherwise people cannot switch keywords.

[yilmazdurmaz]

Thanks for critics. Helps to extend the content.

This is actually not correct, if braces are forgotten, best if that you still use {print} in your translation

Actually, there are some "blocking" settings on Weblate that prevent some changes we made to be saved safely or committed, one is about this curly braces that will keep the translation state as "fuzzy". rules fine to have, so for the moment it is best to just use translated words to keep the word order. that way, when the source is corrected later, anyone that understands this trick can check and see what needs be replaced in any language.

and also change this in English. Otherwise people cannot switch keywords.

This is one nice thing we have, there is even a fast way to do that, but this needs a careful programmer's eye to catch typos and/or missing braces/quotes. I will clear and try adding this part later when it is also clear in my mind to put into sentences.