Thread: Easy language switching for the documentation website
Hi guys, For now, the documentation has only two full and up-to-date translations : Japenese and French... so i guess what i'm gonna talk about will only concern french and japanese speaking people. From my personnal experience, I've talked with a lot of French-speaking PostgreSQL users about the documentation. Most of them read both the french and the english version, because when they have difficulties to understand a paragraph, it's a good thing to go to the translations and get a second chance to understand. It's also usefull when you're confused by weird translations. For exemple "deadlock" is sometimes translated as "verrous morts" which sounds really strange when you first read it :) Anyway, for the french documentation we ended putting a small javascript link on each page to jump directly to the english version. For now, it's only available on the 9.1 doc ( just click on the link named "Version Anglaise" on the left ) : http://docs.postgresql.fr/9.1/explicit-locking.html This works with a very simple js that goes like that : function jump_to_english() {var fr_url = location.href;var fr_pattern = "http://docs.postgresql(.fr|fr.org)/([7-9].[0-4])";varen_pattern = "http://www.postgresql.org/docs/$2/static";var reg=newRegExp(fr_pattern, "");window.location = fr_url.replace(reg,en_pattern) ; } So far people seem to like, the only problem is that once you've jump from French to English, you might want to go backward as easily :) So here my question : could we add a javascript like the one above on each english documentation page ? Of course i would have to adapted to support also Japanese (and maybe german) If think this would be a big improvements for non-english users and probably it could motivate people to translate the doc in other languages. By making existing translations more visible, some people may ask themselves : "why not translating this page in my own language ?" I know javascript is not active on every browser and this code is a quick and dirty hack. But it's simple and it works fine so i really it's worth trying :-) Any comments on this is more than welcome ! Regards, -- damien clochard dalibo.com | dalibo.org
On Thu, Jul 7, 2011 at 23:24, damien clochard <damien@dalibo.info> wrote: > Hi guys, > > For now, the documentation has only two full and up-to-date translations > : Japenese and French... so i guess what i'm gonna talk about will only > concern french and japanese speaking people. > > From my personnal experience, I've talked with a lot of French-speaking > PostgreSQL users about the documentation. Most of them read both the > french and the english version, because when they have difficulties to > understand a paragraph, it's a good thing to go to the translations and > get a second chance to understand. It's also usefull when you're > confused by weird translations. For exemple "deadlock" is sometimes > translated as "verrous morts" which sounds really strange when you first > read it :) > > Anyway, for the french documentation we ended putting a small javascript > link on each page to jump directly to the english version. > > For now, it's only available on the 9.1 doc ( just click on the link > named "Version Anglaise" on the left ) : > > http://docs.postgresql.fr/9.1/explicit-locking.html > > This works with a very simple js that goes like that : > > function jump_to_english() { > var fr_url = location.href; > var fr_pattern = "http://docs.postgresql(.fr|fr.org)/([7-9].[0-4])"; > var en_pattern = "http://www.postgresql.org/docs/$2/static"; > var reg=new RegExp(fr_pattern, ""); > window.location = fr_url.replace(reg,en_pattern) ; > } > > > So far people seem to like, the only problem is that once you've jump > from French to English, you might want to go backward as easily :) > > So here my question : could we add a javascript like the one above on > each english documentation page ? Of course i would have to adapted to > support also Japanese (and maybe german) > > If think this would be a big improvements for non-english users and > probably it could motivate people to translate the doc in other > languages. By making existing translations more visible, some people may > ask themselves : "why not translating this page in my own language ?" > > I know javascript is not active on every browser and this code is a > quick and dirty hack. But it's simple and it works fine so i really it's > worth trying :-) > > Any comments on this is more than welcome ! This thing relies upon the URLs being the same, right? So if we want to do that, why do we need to fiddle with javascript - we could just put links directly into the templates and have "real links" instead of javascript, no? -- Magnus Hagander Me: http://www.hagander.net/ Work: http://www.redpill-linpro.com/
Le 08/07/2011 16:01, Magnus Hagander a écrit : > On Thu, Jul 7, 2011 at 23:24, damien clochard <damien@dalibo.info> wrote: >> Hi guys, >> >> For now, the documentation has only two full and up-to-date translations >> : Japenese and French... so i guess what i'm gonna talk about will only >> concern french and japanese speaking people. >> >> From my personnal experience, I've talked with a lot of French-speaking >> PostgreSQL users about the documentation. Most of them read both the >> french and the english version, because when they have difficulties to >> understand a paragraph, it's a good thing to go to the translations and >> get a second chance to understand. It's also usefull when you're >> confused by weird translations. For exemple "deadlock" is sometimes >> translated as "verrous morts" which sounds really strange when you first >> read it :) >> >> Anyway, for the french documentation we ended putting a small javascript >> link on each page to jump directly to the english version. >> >> For now, it's only available on the 9.1 doc ( just click on the link >> named "Version Anglaise" on the left ) : >> >> http://docs.postgresql.fr/9.1/explicit-locking.html >> >> This works with a very simple js that goes like that : >> >> function jump_to_english() { >> var fr_url = location.href; >> var fr_pattern = "http://docs.postgresql(.fr|fr.org)/([7-9].[0-4])"; >> var en_pattern = "http://www.postgresql.org/docs/$2/static"; >> var reg=new RegExp(fr_pattern, ""); >> window.location = fr_url.replace(reg,en_pattern) ; >> } >> >> >> So far people seem to like, the only problem is that once you've jump >> from French to English, you might want to go backward as easily :) >> >> So here my question : could we add a javascript like the one above on >> each english documentation page ? Of course i would have to adapted to >> support also Japanese (and maybe german) >> >> If think this would be a big improvements for non-english users and >> probably it could motivate people to translate the doc in other >> languages. By making existing translations more visible, some people may >> ask themselves : "why not translating this page in my own language ?" >> >> I know javascript is not active on every browser and this code is a >> quick and dirty hack. But it's simple and it works fine so i really it's >> worth trying :-) >> >> Any comments on this is more than welcome ! > > > This thing relies upon the URLs being the same, right? Yes. For the french doc, we keep the original english filenames. I assume the japanese and germans do the same.... > So if we want > to do that, why do we need to fiddle with javascript - we could just > put links directly into the templates and have "real links" instead of > javascript, no? > Sure! I just don't know how to do that :) The javascript way was just easier for me :) If someone wants to implement a real link it's even better :) -- damien clochard dalibo.com | dalibo.org
On Fri, Jul 8, 2011 at 3:01 PM, Magnus Hagander <magnus@hagander.net> wrote: > > This thing relies upon the URLs being the same, right? So if we want > to do that, why do we need to fiddle with javascript - we could just > put links directly into the templates and have "real links" instead of > javascript, no? Yeah. I also wonder if it's a good idea to add so many "official" looking links to sites that we don't manage. We have spent a lot of time ensuring that our primary site is mirrored across multiple servers and is able to handle error conditions gracefully. I'd rather see the foreign language docs on the same servers, and also with the same stylesheets, banners and menus etc, to avoid confusing the user by sending them to a completely different site. -- Dave Page Blog: http://pgsnake.blogspot.com Twitter: @pgsnake EnterpriseDB UK: http://www.enterprisedb.com The Enterprise PostgreSQL Company
On Fri, Jul 8, 2011 at 17:06, Dave Page <dpage@pgadmin.org> wrote: > On Fri, Jul 8, 2011 at 3:01 PM, Magnus Hagander <magnus@hagander.net> wrote: >> >> This thing relies upon the URLs being the same, right? So if we want >> to do that, why do we need to fiddle with javascript - we could just >> put links directly into the templates and have "real links" instead of >> javascript, no? > > Yeah. I also wonder if it's a good idea to add so many "official" > looking links to sites that we don't manage. We have spent a lot of > time ensuring that our primary site is mirrored across multiple > servers and is able to handle error conditions gracefully. I'd rather > see the foreign language docs on the same servers, and also with the > same stylesheets, banners and menus etc, to avoid confusing the user > by sending them to a completely different site. Yes, that is the other side that needs to be considered. Also the neverending debate on what to do when the translation is out of date (e.g. at every point release or so..) -- Magnus Hagander Me: http://www.hagander.net/ Work: http://www.redpill-linpro.com/
2011/7/8 Dave Page <dpage@pgadmin.org>: > On Fri, Jul 8, 2011 at 3:01 PM, Magnus Hagander <magnus@hagander.net> wrote: >> >> This thing relies upon the URLs being the same, right? So if we want >> to do that, why do we need to fiddle with javascript - we could just >> put links directly into the templates and have "real links" instead of >> javascript, no? > > Yeah. I also wonder if it's a good idea to add so many "official" > looking links to sites that we don't manage. We have spent a lot of > time ensuring that our primary site is mirrored across multiple > servers and is able to handle error conditions gracefully. I'd rather > see the foreign language docs on the same servers, and also with the > same stylesheets, banners and menus etc, to avoid confusing the user > by sending them to a completely different site. I fully agree here. IMHO debian use the right way to do that: http://www.debian.org/releases/stable/amd64/pr01.html Add a .de or a .fr or .. at the end offer you the relevant page. By default it is english, and by default it gets your browser language. Nothing prevent us to have a list of supported language to help the user navigate the documentation. It should also be easy enough to write on the page when then translation seems outdated (from file timestamp between original and translated version for example), I didn't check but the issue is not limited to PostgreSQL and I am pretty sure some open source projects did find a good way to handle that). -- Cédric Villemain 2ndQuadrant http://2ndQuadrant.fr/ PostgreSQL : Expertise, Formation et Support
On Sat, Jul 9, 2011 at 00:48, Cédric Villemain <cedric.villemain.debian@gmail.com> wrote: > 2011/7/8 Dave Page <dpage@pgadmin.org>: >> On Fri, Jul 8, 2011 at 3:01 PM, Magnus Hagander <magnus@hagander.net> wrote: >>> >>> This thing relies upon the URLs being the same, right? So if we want >>> to do that, why do we need to fiddle with javascript - we could just >>> put links directly into the templates and have "real links" instead of >>> javascript, no? >> >> Yeah. I also wonder if it's a good idea to add so many "official" >> looking links to sites that we don't manage. We have spent a lot of >> time ensuring that our primary site is mirrored across multiple >> servers and is able to handle error conditions gracefully. I'd rather >> see the foreign language docs on the same servers, and also with the >> same stylesheets, banners and menus etc, to avoid confusing the user >> by sending them to a completely different site. > > I fully agree here. > > IMHO debian use the right way to do that: > http://www.debian.org/releases/stable/amd64/pr01.html > > Add a .de or a .fr or .. at the end offer you the relevant page. By > default it is english, and by default it gets your browser language. > Nothing prevent us to have a list of supported language to help the > user navigate the documentation. > > It should also be easy enough to write on the page when then > translation seems outdated (from file timestamp between original and > translated version for example), I didn't check but the issue is not > limited to PostgreSQL and I am pretty sure some open source projects > did find a good way to handle that). Timestamp does not work for determining if it's up to date. Withan older timestamp it's almost guaranteed to be out of date, but with a newer timestamp there is nothing saying *what* was changed at the later time. I think system like gettext allow a more sophisticated way than just timestamp comparison, and we need something along that line. But I don't know the details of how they work. -- Magnus Hagander Me: http://www.hagander.net/ Work: http://www.redpill-linpro.com/