From 802d1932703e9b7e9d60be7d60aea449d3c23ac7 Mon Sep 17 00:00:00 2001 From: "@s.roertgen" Date: Thu, 25 Jan 2024 13:52:59 +0100 Subject: [PATCH 1/4] Add blog post about serving skohub vocabs without language tags #32 --- .../index.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 content/blog/2024-01-24-uris-without-language-tags/index.md diff --git a/content/blog/2024-01-24-uris-without-language-tags/index.md b/content/blog/2024-01-24-uris-without-language-tags/index.md new file mode 100644 index 0000000..70e51c3 --- /dev/null +++ b/content/blog/2024-01-24-uris-without-language-tags/index.md @@ -0,0 +1,63 @@ +--- +title: Breaking Improvement - SkoHub Vocabs Without Language Tags in URLs +date: "2024-01-24" +authors: [{lastname: "Rörtgen", + firstname: "Steffen", + id: "https://lobid.org/team/sr#"}] +--- + +If you have worked with SkoHub Vocabs before, you might have noticed that the URLs in the address bar had a little special feature that you don't encounter very often, a language tag before the `.html`: + +`https://skohub.io/dini-ag-kim/hochschulfaechersystematik/heads/master/w3id.org/kim/hochschulfaechersystematik/scheme.de.html` + +Why did we need this? + +We wanted Internationalization features to be able to navigate multiple languages. +Normally this is done via a subdomain or adding a language tag behind the domain name like `https://w3id.org/kim/hochschulfaechersystematik/en/`. +But this does not work for SkoHub Vocabs since the we use the URIs from the turtle files as IDs for the concept. +Changing the URI by adding a language tag somewhere would break the whole concept of SkoHub Vocabs. + +So it was decided to add the language at the end of the URL by using Apache Multiviews features. +But this lead to some inconveniences: + +- SkoHub Vocabs needed to be served by an Apache Webserver +- The webserver needed special configuration +- [SkoHub Docker Vocabs](https://github.com/skohub-io/skohub-docker-vocabs), which is served via GitHub Pages, always needed a specific link to an index.{language}.html file, since GitHub Pages only looks for an `index.html` +- The build directory grew quite a bit, since there were dedicated html pages built for every language + +In order to overcome these issues we decided to change this behaviour and just build one html page with a functionality to switch languages. + +The shown language is now chosen the following way: + +- by using your browser language +- if you switched languages in the application the chosen language is taken +- if a language is not present, a default language present in the vocabulary is used + +To point users to a specific language, you can use a query parameter `lang=` like: + +`https://w3id.org/kim/hcrt/scheme?lang=uk` + +Since SkoHub Vocabs also used the language tag of the URL internally to determine which language to serve a lot of changes had to be done in the codebase. +But overall this resulted in a much reduced size of the built vocabularies and more flexibility on serving the vocabularies. + +## What to do if I'm running my own webhook server? + +If you are running your own webhook server, you should upgrade the following way: + +- follow the steps outlined in the webhook repository to [rebuild vocabularies](https://github.com/skohub-io/skohub-webhook#rebuilding-vocabularies) +- this will rebuild all still existing branches you are currently serving +- setup a redirect in your apache config, so that links that still have `...de.html` will be redirected to `...html?lang=de`: +``` +# Redirect from ...filename.LANGCODE.html to ...filename.html?lang=LANGCODE + RewriteRule ^(.+)\.([a-z]{2})\.html$ $1.html?lang=$2 [L,R=301] +``` +- after that you should be good! + +## Anything else? + +During developing the script to rebuild all existing vocabularies, I noticed that we are serving a lot of branches that do not exist anymore. +SkoHub Webhook builds a vocabulary for every branch, you are setting up and pushing to. +But the webhook service does not get notified, when a branch is deleted. +This way we end up having lots of files for branches that no one needs anymore. +In order to clean this up a bit, we will soon add a script to clean the dist directory up and remove those no longer needed files. + From e4f28b09effd45b5fe25dc28e6be46fff5648342 Mon Sep 17 00:00:00 2001 From: Adrian Pohl Date: Mon, 29 Jan 2024 14:04:52 +0100 Subject: [PATCH 2/4] Adjusting title, adding headings (#32) --- .../index.md | 28 ++++++++++++------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/content/blog/2024-01-24-uris-without-language-tags/index.md b/content/blog/2024-01-24-uris-without-language-tags/index.md index 70e51c3..e51bdca 100644 --- a/content/blog/2024-01-24-uris-without-language-tags/index.md +++ b/content/blog/2024-01-24-uris-without-language-tags/index.md @@ -1,11 +1,13 @@ --- -title: Breaking Improvement - SkoHub Vocabs Without Language Tags in URLs -date: "2024-01-24" +title: Re-working SkoHub Vocabs internationalization featues +date: "2024-01-30" authors: [{lastname: "Rörtgen", firstname: "Steffen", id: "https://lobid.org/team/sr#"}] --- +## In the past: Internationalization with drawbacks + If you have worked with SkoHub Vocabs before, you might have noticed that the URLs in the address bar had a little special feature that you don't encounter very often, a language tag before the `.html`: `https://skohub.io/dini-ag-kim/hochschulfaechersystematik/heads/master/w3id.org/kim/hochschulfaechersystematik/scheme.de.html` @@ -18,16 +20,16 @@ But this does not work for SkoHub Vocabs since the we use the URIs from the turt Changing the URI by adding a language tag somewhere would break the whole concept of SkoHub Vocabs. So it was decided to add the language at the end of the URL by using Apache Multiviews features. -But this lead to some inconveniences: +But this lead to some drawbacks: - SkoHub Vocabs needed to be served by an Apache Webserver - The webserver needed special configuration - [SkoHub Docker Vocabs](https://github.com/skohub-io/skohub-docker-vocabs), which is served via GitHub Pages, always needed a specific link to an index.{language}.html file, since GitHub Pages only looks for an `index.html` - The build directory grew quite a bit, since there were dedicated html pages built for every language -In order to overcome these issues we decided to change this behaviour and just build one html page with a functionality to switch languages. +## Switching to one page for all languages -The shown language is now chosen the following way: +In order to overcome these issues we decided to change this behaviour and just build one html page with a functionality to switch languages. The shown language is now chosen the following way: - by using your browser language - if you switched languages in the application the chosen language is taken @@ -40,23 +42,29 @@ To point users to a specific language, you can use a query parameter `lang=` lik Since SkoHub Vocabs also used the language tag of the URL internally to determine which language to serve a lot of changes had to be done in the codebase. But overall this resulted in a much reduced size of the built vocabularies and more flexibility on serving the vocabularies. +## Benefits of the new approach + +This new internationalization approach brings lots of improvements: + +- ... + + ## What to do if I'm running my own webhook server? If you are running your own webhook server, you should upgrade the following way: -- follow the steps outlined in the webhook repository to [rebuild vocabularies](https://github.com/skohub-io/skohub-webhook#rebuilding-vocabularies) -- this will rebuild all still existing branches you are currently serving -- setup a redirect in your apache config, so that links that still have `...de.html` will be redirected to `...html?lang=de`: +- Follow the steps outlined in the webhook repository to [rebuild vocabularies](https://github.com/skohub-io/skohub-webhook#rebuilding-vocabularies). This will rebuild all still existing branches you are currently serving. +- Set up a redirect in your apache config, so that links that still have `...de.html` will be redirected to `...html?lang=de`: ``` # Redirect from ...filename.LANGCODE.html to ...filename.html?lang=LANGCODE RewriteRule ^(.+)\.([a-z]{2})\.html$ $1.html?lang=$2 [L,R=301] ``` -- after that you should be good! +- After that you should be good! ## Anything else? During developing the script to rebuild all existing vocabularies, I noticed that we are serving a lot of branches that do not exist anymore. -SkoHub Webhook builds a vocabulary for every branch, you are setting up and pushing to. +SkoHub Webhook currently builds a vocabulary for every branch, you are setting up and pushing to. But the webhook service does not get notified, when a branch is deleted. This way we end up having lots of files for branches that no one needs anymore. In order to clean this up a bit, we will soon add a script to clean the dist directory up and remove those no longer needed files. From 3a1105723187918a8c0e9e7dc507c8c471be9ae7 Mon Sep 17 00:00:00 2001 From: "@s.roertgen" Date: Wed, 31 Jan 2024 08:41:29 +0100 Subject: [PATCH 3/4] Add improvement section #32 --- content/blog/2024-01-24-uris-without-language-tags/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/blog/2024-01-24-uris-without-language-tags/index.md b/content/blog/2024-01-24-uris-without-language-tags/index.md index e51bdca..3cea42e 100644 --- a/content/blog/2024-01-24-uris-without-language-tags/index.md +++ b/content/blog/2024-01-24-uris-without-language-tags/index.md @@ -46,8 +46,9 @@ But overall this resulted in a much reduced size of the built vocabularies and m This new internationalization approach brings lots of improvements: -- ... - +- SkoHub Vocabs is now independent from the underlying webserver +- The size of the vocabularies is drastically reduced, especially for vocabularies with lots of languages +- [SkoHub Docker Vocabs](https://github.com/skohub-io/skohub-docker-vocabs) is now simpler to setup since we only have "normal" `index.html` files that it knows how to handle ## What to do if I'm running my own webhook server? From d2a6927c4404c1b84b67bc6ad088a9a0b106ebb3 Mon Sep 17 00:00:00 2001 From: "@s.roertgen" Date: Wed, 31 Jan 2024 08:41:56 +0100 Subject: [PATCH 4/4] Adjust date #32 --- content/blog/2024-01-24-uris-without-language-tags/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/blog/2024-01-24-uris-without-language-tags/index.md b/content/blog/2024-01-24-uris-without-language-tags/index.md index 3cea42e..7d76eae 100644 --- a/content/blog/2024-01-24-uris-without-language-tags/index.md +++ b/content/blog/2024-01-24-uris-without-language-tags/index.md @@ -1,6 +1,6 @@ --- title: Re-working SkoHub Vocabs internationalization featues -date: "2024-01-30" +date: "2024-01-31" authors: [{lastname: "Rörtgen", firstname: "Steffen", id: "https://lobid.org/team/sr#"}]