Docs navigation is different when switching language

sfederici commented 1 year ago

Description

Both the content and the order of items in the menu in the left bar of the website are different when I read the website pages in English or Italian.

Side note: some languages in the topright dropdown menu to switch language show up with the first letter in capital (e.g. English, Deutsch, etc), other ones show up with the first letter in small capital (e.g. francais, polski, italian, etc)

Steps to reproduce

Switch the website language from English to Italian and look at the left bar menu

Demonstration(s) and additional context

go, e.g., to https://scratchaddons.com/docs/getting-started/installing/. You can see this menu
now switch to Italian. You can see this menu

In the Italian menu, Localization (localizzazione) is above Developing (sviluppo) and the Reference and Policies items are missing.

Environment

Browser: Firefox 109 and Chrome 109 Scratch Addons version: 1.30.1 Operating system: macOS Big Sur

Hans5958 commented 1 year ago

This is intentional. Policies are not translated because..., it is a official policy that should be better on having one version. Reference are still being hold due to the scale, but maybe @WorldLanguages wants to pour in again about this one.

For the note, this has been asked by our Turkish translators on the dev Discord server: https://discord.com/channels/751206349614088204/779369057488338945/1008388420650934272.

sfederici commented 1 year ago

Sorry, I don't understand. I understand that you can decide that something won't be translated (even if, it is not a very good idea for me) but, even if it is not translated, this can't imply that it should disappear from the leftbar menu. If it is not translated, the user will see the English version of this item in their foreign language menu. Otherwise, this information would simply disappear for foreign language readers of the documentation. And this cannot be right.

So, please, consider at least to add English, untranslated items to the foreign language menus.

mxmou commented 1 year ago

@Hans5958 This is a valid suggestion. Even if hiding certain pages is intentional, I don't think it makes sense. All pages should be easily accessible from all languages (related: #92), and the policies are especially important.

The issue also mentions Developing and Localization being swapped in certain languages. Apparently this is because the "weight" is set to 2 for both pages. I think it would be better to make the order consistent.

BroJac5246 commented 1 year ago

This is intentional. Policies are not translated because..., it is a official policy that should be better on having one version. Reference are still being hold due to the scale, but maybe @WorldLanguages wants to pour in again about this one.

For the note, this has been asked by our Turkish translators on the dev Discord server: https://discord.com/channels/751206349614088204/779369057488338945/1008388420650934272.

We should translate the policies and include a warning that they aren't the official ones.

Hans5958 commented 1 year ago

Alright folks, I'm still discussing this together with WL, and I would want to give my thoughts first. Perhaps you guys wanted to give opinions about these.

Last time on #92, I tried to answer the question of "Should untranslated[^1] pages be shown on the docs?" With some adjustments I have put so the threshold is 0%, letting untranslated pages be live on the website.

Mind that the changes only focused on untranslated pages. This does not include parts that can't be translated (at all, like the pages are not submitted to be translated), such as the reference docs and policies. This is why I delay closing it, in case there are other requests.

Regarding the pages that can't be translated on the docs, the fact is that I really wish to have all of the docs translated, including the reference docs and policies. But then, WL didn't want this to be translated, in which I agreed upon. So, that is another question: "Should reference docs and policies be translated?"

If all comes down to a "no", there is the question of "What should happen on pages that can't be translated on the other languages?" which the answer on this issue is to "just show it." This could be intepreted in multiple ways (surprisingly).

Assume it untranslated; copy the English text. e.g. /docs/id/reference/addon-manifest/ would include the English copy. The easiest way, which is also the default, and probably what people wishing for. Also, I heard that people want to navigate while being inside their language. But, something else needed to be considered.
- Assume that a language is fully translated: Would people like if every page is translated, but then have these parts in English? (This is what happened on the Changelog page, where the changelog entries and highlight contents are not translated. On second thought I want to open it, but I would need help of translators to re-add Highlights by themselves with the future tool to show the update notification of all versions, but this is for another time. Would you guys want that?)
Have the links on the sidebar, but then it redirects to English. e.g. /docs/id/reference/addon-manifest/ would redirect to /docs/reference/addon-manifest/. Another alternative that I'm thinking, but then if you want to stay on that language, you can't.

And I haven't consider the blog, which is still left untranslated. This is also left for another time.

As of the ordering, I can see the concern. Probably I would have it so it orders on the file name instead (e.g. addon-manifest.md). The file names on English, and it would be consistent across all languages.

[^1]: untranslated, as in, pages that are submitted to be translated, but haven't been translated

sfederici commented 1 year ago

Regarding the pages that can't be translated on the docs, the fact is that I really wish to have all of the docs translated, including the policies. But then, WL didn't want this to be translated, in which I agreed upon. So, that is another question: "Should reference docs and policies be translated?"

To me, as much as possible should be translated. I agree that the policies, that are a "legal" document, could be wrongly translated. So, the policies could be not translated.

"What should happen on pages that can't be translated on the other languages?" which the answer on this issue is to "just show it."

Just show it in English.

I heard that people want to navigate while being inside their language. But, something else needed to be considered.

If possibile, links in a translated page to other pages should always bring to translated pages, if available.

Would people like if every page is translated, but then have these parts in English?

I guess they would like it. Otherwise they could miss important pages. A warning at the top of the page (to clarify that the page is not shown in English by mistake) could be added.

(This is what happened on the Changelog page, where the changelog entries and highlight contents are not translated. On second thought I want to open it, but I would need help of translators to re-add Highlights by themselves with the future tool to show the update notification of all versions, but this is for another time. Would you guys want that?)

I think the Changelog could not be translated. If the general opinion if that it should, I'm ready to translate it and re-add Highlights

2. Have the links on the sidebar, but then it redirects to English.

Yes, this is important.

As of the ordering, I can see the concern. Probably I would have it so it orders on the file name (e.g. addon-manifest.md). The file names on English, and it would be consistent across all languages.

I agree.

ilbailba commented 1 year ago

@Hans5958 In response to item 2: Can't it be done like this? Have the references and policies section on the left and, for example, https://scratchaddons.com/language/docs/policies/, but the text inside is in English. In this way, you can reach that page without switching to English.

The browsing history looks like this: https://scratchaddons.com/language/docs/getting-started/ https://scratchaddons.com/language/docs/reference/ (but in English) https://scratchaddons.com/language/docs/faq/

I hope I was able to explain what I mean.

Also for the

"Assume that a language is fully translated: Would people like if every page is translated, but then have these parts in English?"

you mentioned: Yes they would, but is it worth it if they didn't know those pages existed? We're talking about legal issues and important information for coding, I think this can be ignored. Unless of course you let us translate.

To summarize my views:

The https://scratchaddons.com/language/docs/reference/ page and all the pages below should be added to the transifex and optionally a warning "These strings can be changed later, so remember this when translating" (W_L's guilt not to feel it).
The https://scratchaddons.com/language/docs/policies/ page should exist but no translation. The reason for this is, as you know, while installing some programs, you will see a contract that they want you to accept. Even though there are dozens of language options in the app, most of the time the contract has been translated into only a few languages or is available in only one language.
In addition, I think that the blog page should be opened for translation.

ilbailba commented 1 year ago

@sfederici

I think the Changelog could not be translated. If the general opinion if that it should, I'm ready to translate it and re-add Highlights

I'm in favor of its translation into other languages. Because the bugs fixed in the updates can only be viewed by users there.

Hans5958 commented 1 year ago

@sfederici @ilbailba: Perhaps that I may not clear enough to describe the two variations that I'm thinking of. I have edited the comment to reflect what am I thinking about it. I hope it is clearer now.

@ilbailba, what you described is the first variation that I'm thinking (Assume it untranslated; copy the English text). Again, this is my assumption of what people wanted, including you, it seems.

Regarding of the opinion of "people may miss some of the pages." I can see that. But, allow me to describe this stance: We encourage for people to refer to the English version at all times. For some of these docs, we only focused on the English versions by just strictly linking the English version. This includes the /translate redirect, the privacy policy, the blog posts, and so on. This doesn't mean that these pages can't be translated, but it is a choice to keep it focused on the English versions.

ScratchAddons / website-v2