Management and automation of multilingualism: Comprehensive installation instructions

This document contains instructions for implementing multilingual documentation for The Chronicles of Ultimate Retro Station project. The system is based on automatic translation, the i18n plugin and Mermaid charts in English. Check the repository for the correct versions of the python compiler and mkdocs.yml, examples below.

---

1. Environment preparation

Install the necessary Python libraries on your system. This covers MkDocs, a UI theme, language support, and a translation tool.

# Perusympäristö ja teema
pip install mkdocs-material

# Kielituki ja navigoinnin hallinta
pip install mkdocs-static-i18n

# Automaattinen kääntäjätyökalu
pip install deep-translator

---

2. Translation script (translate_docs.py)

---

Does not translate code or text blocks, Mermaid patterns, only explanatory text from image links.

import os
import re
from deep_translator import GoogleTranslator
from dotenv import load_dotenv

# Ladataan asetukset .env-tiedostosta
load_dotenv()

docs_dir = os.getenv('DOCS_DIR', 'docs')
source_lang = os.getenv('SOURCE_LANG', 'fi')
target_lang = os.getenv('TARGET_LANG', 'en')

def translate_markdown(content):
    translator = GoogleTranslator(source=source_lang, target=target_lang)
    lines = content.split('\n')
    translated_lines = []
    is_code_block = False

    # Regex-kuviot:
    # 1. Kuvalinkit: ![alt](polku)
    # 2. Tavalliset linkit: [teksti](polku)
    image_or_link_pattern = re.compile(r'(!?\[.*?\]\(.*?\))')

    for line in lines:
        # 1. SUOJAUS: Koodilohkot (```text, ```mermaid, jne.)
        if line.strip().startswith('```'):
            is_code_block = not is_code_block
            translated_lines.append(line)
            continue

        # Jos ollaan koodilohkon sisällä tai rivi on tyhjä, kopioidaan sellaisenaan
        if is_code_block or not line.strip():
            translated_lines.append(line)
            continue

        # 2. SUOJAUS: Kuvalinkit ja polut
        # Jos rivi sisältää Markdown-linkin tai kuvan, on turvallisinta 
        # kääntää se varoen tai ohittaa automaatio, jotta polku ei hajoa.
        # Tässä versiossa ohitetaan rivit, joissa on kuvia/linkkejä virheiden välttämiseksi.
        if image_or_link_pattern.search(line):
            # Vaihtoehtoisesti voisit kääntää vain osia, mutta polkujen 
            # rikkoutuminen on suurin riski, joten säilytetään alkuperäinen rivi.
            translated_lines.append(line)
            continue

        # 3. KÄÄNNÖS: Tavalliset tekstirivit
        try:
            translated = translator.translate(line)
            if translated is not None:
                translated_lines.append(translated)
            else:
                translated_lines.append(line)
        except Exception as e:
            print(f"Virhe kääntäessä riviä: {line[:30]}... -> {e}")
            translated_lines.append(line)

    return '\n'.join(translated_lines)

def process_docs():
    if not os.path.exists(docs_dir):
        print(f"Virhe: Kansiota '{docs_dir}' ei löydy. Tarkista .env tai polku.")
        return

    for root, dirs, files in os.walk(docs_dir):
        for file in files:
            # Käsitellään vain .md tiedostot, mutta ohitetaan jo käännetyt (.en.md)
            if file.endswith('.md') and not file.endswith(f'.{target_lang}.md'):
                path = os.path.join(root, file)
                new_path = os.path.join(root, file.replace('.md', f'.{target_lang}.md'))

                print(f"Käsitellään: {path} -> {new_path}")

                try:
                    with open(path, 'r', encoding='utf-8') as f:
                        content = f.read()

                    translated_content = translate_markdown(content)

                    with open(new_path, 'w', encoding='utf-8') as f:
                        f.write(translated_content)
                except Exception as e:
                    print(f"Tiedostovirhe {path}: {e}")

    if __name__ == "__main__":
        print(f"Aloitetaan käännös: {source_lang} -> {target_lang}")
        process_docs()
        print("\nKaikki tiedostot käsitelty!")

3. MkDocs configuration (mkdocs.yml)

Let's add the following settings to the mkdocs.yml file to activate language switching and Mermaid support in the user interface.

    site_name: The Chronicles of Ultimate Retro Station

    theme:
    name: material
    language: fi
    features:
        - i18n.nav
        - navigation.tabs
        - content.code.copy

    plugins:
    - search
    - i18n:
        default_language: fi
        languages:
            fi: 
            name: Suomi
            build: true
            en: 
            name: English
            build: true
        nav_translations:
            en:
            "JÄRJESTELMÄHISTORIA": "SYSTEM HISTORY"
            "ASENNUS": "INSTALLATION"

    markdown_extensions:
    - pymdownx.superfences:
        custom_fences:
            - name: mermaid
            class: mermaid
            format: !!python/name:pymdownx.superfences.fence_code_format

---

4. Workflow and rules

Follow this routine when updating the documentation:

• Writing: Create a new .md file in the docs/ folder and write the content in Finnish.
• Mermaid charts: Generate charts directly in English (eg node1["CPU"]). Do not use gimmicks in the technical identifiers of diagrams.
• Translation: Run python translate_docs.py. This will update the English versions.
• Testing: Run mkdocs serve and make sure that the language changer in the upper right corner redirects to the right pages.

---

5. Troubleshooting

Mermaid not showing up: Make sure the pymdownx.superfences extension is configured correctly in the mkdocs.yml file.

Translation breaks: Google Translate's free interface has character limits per call. The script translates line by line to avoid this.

Language changer is missing: Make sure i18n.nav is added to the theme's features list.

---

Multilingual management and troubleshooting

This instruction describes how to keep the Finnish and English versions of the project synchronized and how to solve the most common navigation problems.

1. Description of the problem (Case Study)

At the beginning of the project, the navigation was not translated into English, although the settings seemed to be fine. The reason was two factors:

1. Version conflict: Version 1.x of mkdocs-static-i18n was used, but the settings followed the old 0.x standard.

2. Plugin conflict: The awesome-pages plugin tried to manage navigation automatically, which prevented manual translations from being activated.

2. Solution: Correct configuration

In the current version (v1.x+), the translations must be placed directly under the target language in the mkdocs.yml file.

Correct structure:

---

    plugins:
    - i18n:
        languages:
            - locale: fi
            default: true
            - locale: en
            nav_translations:  # TÄRKEÄÄ: Sisennetty kielen sisään
                "Suomi-otsikko": "English Title"
        reconfigure_material: true

---

6. Manual driving (Local development)

Whenever you have edited Finnish files, you should run the script in the terminal before starting MkDocs:

    python translate_docs.py  # Luo/päivittää .en.md tiedostot
    mkdocs serve              # Käynnistää esikatselun

7. Automatic run (GitLab CI/CD)

If you want the translation to happen completely automatically every time you send code to GitLab (git push), you should add the script execution to the .gitlab-ci.yml file. In this case, the pipe does the work:

    pages:
        stage: deploy
        script:
            - pip install -r requirements.txt
            - python translate_docs.py  # Skripti kääntää tiedostot CI-ympäristössä
            - mkdocs build              # Rakentaa sivuston, jossa on molemmat kielet
        artifacts:
            paths:
            - public

Requirements.txt specification

• Save this in the project root folder as: requirements.txt

    # MkDocs perusrunko ja suosittu teema
    mkdocs>=1.5.0
    mkdocs-material>=9.0.0

    # Mermaid-tuki ja edistyneet Markdown-laajennukset
    pymdown-extensions>=10.0

    # Monikielisyystuki (i18n)
    mkdocs-static-i18n>=1.2.0

    # Automaattinen kääntäminen (translate_docs.py skriptiä varten)
    deep-translator>=1.11.0

Installation

    pip install -r requirements.txt

Only manual is enabled