Documentation/Welcome: automatically detect user's language

[dsjonny]

It would be fine if we open the documentation in the browser and the user's language page will be loaded. So; the page should be detect the browser's preferred language, and load the documentation for that language.

Only this change need to make at the begining of the page:

var language = window.navigator.userLanguage || window.navigator.language;
var xmlhttp;
var offLineWelcomePage = 'file:///boot/system/documentation/userguide/' + language + '/contents.html';
var onLineWelcomePage = 'http://cgit.haiku-os.org/haiku/plain/docs/userguide/' + language + '/contents.html';

This change can be work in the local version, and in the online version too.

In the offline version I have changed: /boot/home/config/settings/WebPositive/LoaderPages/UserGuide and /boot/home/config/settings/WebPositive/LoaderPages/Welcome at line 10.

There maybe one problem: if there is no documentation available in the given language, the user may got problem.

[dsjonny]

I have attached the locally changed files. These are located in the /boot/home/config/settings/WebPositive/LoaderPages/ path.

[humdinger]

There maybe one problem: if there is no documentation available in the given language, the user may got problem.

Couldn't you check if /boot/system/documentation/userguide/' + language exists and if it doesn't use the English version?

[dsjonny]

Success! :) I could made the changes, but the whole file had to be re-written.

I have attached (replaced the previously attached files) the Welcome and the UserGuide file to the ticket. It was tested with Afrikaans, Hungarian and English language.

How it works? If the docment is exists on the given language locally, than that will be load. If not exists, than try to check the online version. If that is not exists too, than load the online English page.

And I have added another one think: if no page found for the given language locally, and no internet connection, than the user got a message: "Sorry, but no documentation found. :("

[humdinger]

Hmm... doesn't completely work for me. I tested with the German locale.
Even though I have the docs installed locally, it always goes off to the English online version.

After setting the English locale instead, the locally installed document is shown correctly. Removing the English docs, I'm taken to the online version. So for English it works perfectly.

Can it be that the 'language' string you query from the browser isn't always how the doc folders are named, currently:

ca
de
en
es
fi
fr
hu
it
jp
pt_BR
pt_PT
ru
sk
sv_SE
uk
zh_CN

Also, setting a language we don't yet have a translation for, like "Bahasa Indonesia", I'm taken to the English online version, instead of the locally installed English docs.

[dsjonny]

I think it's final...

How it works?

1. it detects the language code (if code contains "-", it will replace with "_"; it the code style is xx-XX, than it will use only 2 char code (for example: de-DE > de, pt-BR > pt_BR, hu > hu))
2. check if local page is available for the given language; if yes, than load it
3. if not, than check if the online page is available for the given language; if yes, load it
4. if not, than check it local English page is available; if yes, load it
5. if not, than check if the online English page is available; if yes, load it
6. if not, than inform the user: "Sorry, but no page found. :("

There is only one problem: if no internet connection available, and no local page present, than it will wait until some seconds/minutes before it inform the user about no page available.

I have tried it with Hungarian, English, Afrikaans (Suid-Afrika), Deutsch (Deutschland) and Portugues (Brasil) languages; with internet present/not present; with page is present/not present.

[humdinger]

There's still something wrong...
Portuguese (Brasil) works, but Portuguese (Portugal) opens English instead. Back to the drawing board... :)

[dsjonny]

I know why: that's because the language code is "pt_PT", so the script translate it to "pt". If I turn of this, than the "de_DE" will not work, because the documentation is use the "de" instead of the "de_DE" in the path name. If I want to detect the "pt_PT" too, than the file needs to have duble script (to check "pt", "pt_PT", "pt_BR", local and online).

So, I think we can do 3 things:

• leave this in this form, but in this case, the user needs to select the Portugal manually
• change the languages which has "sub-language" to the "xx_YY" format (in this case we need to remove some part of the script)
• use single code ("xx") when the "main-code" and the "sub-code" is equal

I prefer the 2nd, because it's logical, but it needs "more work".

[humdinger]

I tend to agree, renaming the folders xx_YY would be best. I'll make Niels aware of this ticket. Let's see what he thinks and what's needed for that change.

[nielx]

I would advise against changing the directory names.

1. It is not in line with common i18n conventions. pt is supposedly the most generic form of the language. Changing it to pt_PT would break that convention.
2. I would not try changing this with our current translation tool. Since nobody knows how it works, it might break things in ways we can't even imagine.

[mmadia]

Replying to dsjonny:

So, I think we can do 3 things:

• leave this in this form, but in this case, the user needs to select the Portugal manually
• change the languages which has "sub-language" to the "xx_YY" format (in this case we need to remove some part of the script)
• use single code ("xx") when the "main-code" and the "sub-code" is equal

Given that the second option is not preferred, which way should we go?

[humdinger]

I have modified dsjonny's Userguide and Welcome with some special cases to always find the correct language subfolder. I also introduced a timeout that will show some explanation after 2 seconds when no page can be shown (which pretty much is only if the user doesn't have an internet connection or our server is down), and added some userguide css.
I'm a pretty bad javascripter and putting the explanation strings into 5 variables looks bad even to my unexperienced eyes... If anyone can improve upon it (or anthing else), please do so. I'll be committing the thing soon.

[humdinger]

new UserGuide Loader file

[humdinger]

new Welcome Loader file

[humdinger]

I'll upload a test.html that shows how the generated language menu has to be changed by the online-tool to apply the same javascript 'trick' to fall back to the online version if a language isn't available offline.

The menu has to change from e.g.: <li><a href="../fr/teammonitor.html"><img src="../images/flags/fr.png" alt="" />Français</a></li> to <li><span onclick="ChangeLang('fr')"><img src="../images/flags/fr.png" alt="" />Français</span></li>

This is the new javascript part:

<script type="text/javascript">
	var onlineBase = 'http://cgit.haiku-os.org/haiku/plain/docs/userguide/';
	var offlineBase = 'file:///boot/system/documentation/userguide/';
	var thisUrl = window.location.href;
	var m = thisUrl.split("userguide/");
	var thisLangPage = m[1];

	function ChangeLang (val) {
		var n = thisLangPage.split("/");
		var newLangPage = thisLangPage.replace(n[0], val);
		var newUrl = offlineBase + newLangPage;
		
		var xmlhttp = new XMLHttpRequest();
		xmlhttp.open("HEAD", newUrl, false);
		xmlhttp.send();
		
		if (xmlhttp.responseText == "") {
			newUrl = onlineBase + newLangPage;
		}
		window.location = newUrl;
	}
</script>

[humdinger]

Test to show a fallback from offline to online page

[humdinger]

improved version

[humdinger]

I attached an improved version of the falback test.html. It respects the home or system location of the userguide and won't switch from the online to the offline version, when the language is switched. If the online version isn't available, it'll show an errorpage.html. (.. which I now realize won't work yet correctly... will fix an upload soon...)

[humdinger]

corrected version...

[humdinger]

The new LoaderPages were committed with hrev49719. I'll leave this ticket open until that fallback-issue at the online tool is fixed.

[pulkomandy]

What's the status on this?