Add Finnish translation of user guide with language switcher

[moritz-gross]

I prototyped internationalization of the docs for Finnish. The English version still lives directly in docs, but we now also support other langues in subfolders like fi, de, etc.

@samimaattaCelia below is your translation running in the same template that's already in use, except that I added a language switcher to it. Is this what you have in mind?
Also, I don't know what you technically mean by "considering different screen readers". Can't we just have one user.md file that has different sections for this?

@NSoiffer I ran jekyll using a mounted Docker container. How did you do local development? I haven't found a gemfile and also some entries could be added to the .gitignore.

Generally, how does hosting the docs work? afaik, there is not GitHub Actions workflow. does it rely on the repo settings and a hardcoded path (so docs I guess?)

As we already have some translations, I wanted to get this started quickly so that you are not blocked.
let me know which parts of this prototype can stay or have to be changed. I haven't worked with Jekyll yet, so I'm very much improvising here.

[NSoiffer]

The docs get moved to github.io via settings/pages:

That's about the extent of my knowledge. AI says we should create docs/en, docs/fi, etc., and then have a docs/index.html page

<script>
  const supportedLanguages = ['en', 'fi', 'es'];
  const defaultLanguage = 'en';

  // 1. Check if the user has a saved preference in localStorage
  let targetLang = localStorage.getItem('selectedLanguage');

  // 2. If no saved preference, detect browser language
  if (!targetLang) {
    const userLang = (navigator.language || navigator.userLanguage).split('-')[0];
    targetLang = supportedLanguages.includes(userLang) ? userLang : defaultLanguage;
  }

  // 3. Redirect only if the user is at the root "/"
  if (window.location.pathname === '/' || window.location.pathname === '/index.html') {
    window.location.replace('/' + targetLang + '/');
  }

  // 4. Function to save preference when they use the switcher
  function changeLanguage(lang) {
    localStorage.setItem('selectedLanguage', lang);
    window.location.href = '/' + lang + '/';
  }
</script>

That seems reasonable. Note: I think users should have a choice of languages, so I asked AI to add that (part of above).

It also said that we can override the default by adding a GitHub action:
For more control over the deployment (especially if using specialized plugins), use a GitHub Actions workflow:

1. Go to your repository Settings > Pages.
2. Under Build and deployment, change the Source to "GitHub Actions".
3. Use a starter workflow for your specific generator (Jekyll, Hugo, etc.) to build and deploy to the gh-pages branch or directly to the site.

To pickup the languages automatically, more changes are needed (according to Gemini):

Since you’re already using Jekyll (as indicated by the MathCAT pull request you are viewing), you can automate the language switcher entirely using Liquid. This means you won't have to update a JavaScript list every time you add a new translation.

Here is how to set up an automated switcher that detects your folders and keeps the user on their current page when they switch:

1. Update _config.yml
   Add a list of your supported language codes to your configuration file. This serves as the "source of truth" for the automation.

YAML

languages:
  - { code: "en", label: "English" }
  - { code: "fi", label: "Suomi" }
  - { code: "es", label: "Español" }

2. Create an Automated Switcher (Liquid)
   Place this code in your navigation or header include file (e.g., _includes/header.html). It automatically calculates the correct path so if a user is reading user-guide.md in English, switching to Finnish takes them directly to the Finnish user-guide.md instead of the homepage.

HTML

<div class="language-picker">
  <select onchange="changeLanguage(this.value)">
    {% for lang in site.languages %}
      {% if page.url contains lang.code %}
        {% assign current_lang = lang.code %}
      {% endif %}
      
      {% comment %} 
        This replaces the current language code in the URL with the new one 
      {% endcomment %}
      <option value="{{ page.url | replace: current_lang, lang.code }}" 
              {% if current_lang == lang.code %}selected{% endif %}>
        {{ lang.label }}
      </option>
    {% endfor %}
  </select>
</div>

<script>
  function changeLanguage(newPath) {
    // Extract the language code from the path (e.g., "/fi/page" -> "fi")
    const langCode = newPath.split('/')[1]; 
    localStorage.setItem('selectedLanguage', langCode);
    window.location.href = newPath;
  }
</script>

3. Handle Missing Translations
   A common issue with automation is when a specific page hasn't been translated yet. If a user tries to switch to Finnish while on a page that only exists in English, they’ll get a 404.

To fix this gracefully, you can add a small check to the script:

The "Safe" Approach: If you want to be 100% safe, have the switcher always link to the homepage of that language (e.g., /fi/) as we discussed previously.

The "Smart" Approach: Use the script above, but add a 404.html page to your repo that detects if the user just tried to switch languages and offers to take them to the English version if the translation is missing.

Summary of the Workflow

1. Add a folder: Create docs/de/.
2. Update config: Add de to _config.yml.
3. Deployment: GitHub Actions/Jekyll builds the site, and the dropdown updates itself automatically across every page on the site.