Hyppää sisältöön

Monikielisyyden hallinta ja automaatio: Kattava asennusohje

Tämä dokumentti sisältää ohjeet The Chronicles of Ultimate Retro Station -projektin dokumentaation monikielisyyden toteuttamiseen. Järjestelmä perustuu automaattiseen kääntämiseen, i18n-lisäosaan ja englanninkielisiin Mermaid-kaavioihin. Tarkasta repositoriosta oikeat versiot python kääntäjästä ja mkdocs.yml:stä, alla esimerkkeinä.

1. Ympäristön valmistelu

Asenna tarvittavat Python-kirjastot järjestelmääsi. Tämä kattaa MkDocsin, käyttöliittymäteeman, kielituen sekä käännöstyökalun.

# 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. Käännösskripti (translate_docs.py)

Ei käännä koodi tai tekstilohkoja, mermaid kuvioita, kuvalinkeistä ainoastaan selittävän tekstin.

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 konfigurointi (mkdocs.yml)

Lisätään seuraavat asetukset mkdocs.yml-tiedostoon, jotta kielenvaihto ja Mermaid-tuki aktivoituvat käyttöliittymässä.

    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. Työnkulku ja säännöt

Noudata tätä rutiinia dokumentaatiota päivittäessäsi:

  • Kirjoittaminen: Luo uusi .md-tiedosto docs/-kansioon ja kirjoita sisältö suomeksi.
  • Mermaid-kaaviot: Luo kaaviot suoraan englanniksi (esim. node1["CPU"]). Älä käytä ääkkösiä kaavioiden teknisissä tunnisteissa.
  • Kääntäminen: Aja python translate_docs.py. Tämä päivittää englanninkieliset versiot.
  • Testaus: Aja mkdocs serve ja varmista, että oikean yläkulman kielenvaihdin ohjaa oikeille sivuille.

5. Vianetsintä

Mermaid ei näy: Varmista, että mkdocs.yml-tiedostossa on pymdownx.superfences-laajennus oikein konfiguroitu.

Käännös katkeaa: Google Translaten ilmaisrajapinnassa on merkkirajatyksiä per kutsu. Skripti kääntää rivi kerrallaan tämän välttämiseksi.

Kielenvaihdin puuttuu: Varmista, että i18n.nav on lisätty teeman features-listalle.

Monikielisyyden hallinta ja vianetsintä

Tämä ohje kuvaa, miten projektin suomen- ja englanninkieliset versiot pidetään synkronoituna ja miten yleisimmät navigaatio-ongelmat ratkaistaan.

1. Ongelman kuvaus (Case Study)

Projektin alkuvaiheessa navigaatio ei kääntynyt englanniksi, vaikka asetukset näyttivät olevan kunnossa. Syynä oli kaksi tekijää:

  1. Versioristiriita: Käytössä oli mkdocs-static-i18n versio 1.x, mutta asetukset noudattivat vanhaa 0.x-standardia.

  2. Plugin-konflikti: awesome-pages -lisäosa yritti hallita navigaatiota automaattisesti, mikä esti manuaalisten käännösten aktivoitumisen.

2. Ratkaisu: Oikea konfiguraatio

Nykyisessä versiossa (v1.x+) käännökset on sijoitettava suoraan kohdekielen alle mkdocs.yml-tiedostossa.

Oikea rakenne:

    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. Manuaalinen ajo (Paikallinen kehitys)

Aina kun olet muokannut suomenkielisiä tiedostoja, sinun tulee ajaa skripti terminaalissa ennen kuin käynnistät MkDocsin:

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

7. Automaattinen ajo (GitLab CI/CD)

Jos halutaan, että käännös tapahtuu täysin automaattisesti aina kun lähetetään koodia GitLabiin (git push), tulee lisätä skriptin suoritus .gitlab-ci.yml -tiedostoon. Tällöin putki hoitaa työn:

    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 määritys

  • Tallenna tämä projektin juurikansioon nimellä: 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
Asennus

    pip install -r requirements.txt

Vain manuaalinen on otettu käyttöön