Skip to content

Commit 476ad10

Browse files
moritz-grossmoritz-gross
committed
Add Finnish translation of user guide with language switcher
 Implements multi-language docs support (issue #504). Adds a language switcher to the layout header, a Finnish translation of users.md (ported from samimaattaCelia's repo), and local Jekyll dev tooling (Gemfile, README, .gitignore entries).
1 parent 3dafd1c commit 476ad10

File tree

8 files changed

+221
-2
lines changed

8 files changed

+221
-2
lines changed

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,3 +52,8 @@ src/speech-bak
5252

5353
Rules/*/*/*.zip
5454
.vs
55+
56+
# local caches when building Jekyll
57+
docs/_site
58+
docs/.jekyll-cache
59+
docs/Gemfile.lock

‎docs/Gemfile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
source "https://rubygems.org"
2+
gem "github-pages", group: :jekyll_plugins
3+
gem "webrick" # HTTP server removed from Ruby 3.0+ stdlib; needed for `jekyll serve`

‎docs/README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# MathCAT Documentation
2+
3+
The docs are built with [Jekyll](https://jekyllrb.com/) using the Cayman theme and hosted on GitHub Pages.
4+
5+
## Multi-language support
6+
7+
Translations live in language subdirectories (e.g. `fi/` for Finnish). Each translated page needs front matter with `lang` and `ref`:
8+
9+
```yaml
10+
---
11+
layout: default
12+
lang: fi
13+
ref: users
14+
title: MathCAT-käyttöopas
15+
---
16+
```
17+
18+
- `lang` — the language code of this page
19+
- `ref` — a shared ID linking translations of the same page (e.g. both `users.md` and `fi/users.md` have `ref: users`)
20+
21+
The language switcher in `_layouts/default.html` uses these to generate links between translations. It only appears on pages that have `ref` set.
22+
23+
To register a new language, add it to `_data/languages.yml`.
24+
25+
## Local development
26+
27+
Run _Jekyll_ from the repo root:
28+
29+
```
30+
docker run --rm -v "${PWD}/docs:/srv/jekyll" -p 4000:4000 jekyll/jekyll bash -c "bundle install && bundle exec jekyll serve --host 0.0.0.0"
31+
```
32+
33+
Then open http://localhost:4000, http://localhost:4000/fi/users, etc..

‎docs/_config.yml‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,11 @@
1-
theme: jekyll-theme-cayman
1+
theme: jekyll-theme-cayman # GitHub Pages theme
2+
3+
# jekyll-github-metadata needs this to resolve site.github.* variables locally;
4+
# GitHub Pages infers it from the environment, but local builds crash without it.
5+
repository: daisy/MathCAT
6+
7+
exclude: [
8+
README.md, # developer docs, not part of the site
9+
Gemfile, # only needed for local builds
10+
Gemfile.lock # only needed for local builds
11+
]

‎docs/_data/languages.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
en:
2+
name: English
3+
fi: # Finnish
4+
name: Suomi

‎docs/_layouts/default.html‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,27 @@ <h2 class="project-tagline">{{ page.description | default: site.description | de
4141
<a href="{{ site.github.zip_url }}" class="btn">Download .zip</a>
4242
<a href="{{ site.github.tar_url }}" class="btn">Download .tar.gz</a>
4343
{% endif %}
44+
45+
{% if page.ref %}
46+
<nav aria-label="Language">
47+
{% for lang_entry in site.data.languages %}
48+
{% assign lang_code = lang_entry[0] %}
49+
{% assign lang_name = lang_entry[1].name %}
50+
{% if lang_code == page.lang %}
51+
<span class="btn">{{ lang_name }}</span> <!-- current language: non-clickable label -->
52+
{% else %}
53+
{% for p in site.pages %}
54+
{% if p.ref == page.ref and p.lang == lang_code %}
55+
<a href="{{ p.url | relative_url }}" class="btn">{{ lang_name }}</a>
56+
{% endif %}
57+
{% endfor %}
58+
{% endif %}
59+
{% endfor %}
60+
</nav>
61+
{% endif %}
62+
4463
</div>
45-
<img src="bolotin-award-badge-web-2.png" style="position: relative; left: 3rem; bottom: 12rem;" alt="Silhouette of Dr. Jacob Bolotin, text reads National Federation of the Blind Bolotin Award Winner"/>
64+
<img src="{{ '/bolotin-award-badge-web-2.png' | relative_url }}" style="position: relative; left: 3rem; bottom: 12rem;" alt="Silhouette of Dr. Jacob Bolotin, text reads National Federation of the Blind Bolotin Award Winner"/>
4665
</header>
4766

4867
<main id="content" class="main-content" role="main">

‎docs/fi/users.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
layout: default
3+
lang: fi
4+
ref: users
5+
title: MathCAT-käyttöopas
6+
---
7+
# MathCAT-käyttöopas
8+
9+
MathCAT-ohjelmistoa käytetään yhdessä ruudunlukijan kanssa. MathCAT-ohjelmisto tulkitsee MathML-koodia ja sen avulla matematiikkaa voi kuunnella ja lukea pistenäytöltä.
10+
11+
## Käytän NVDA-ruudunlukijaa
12+
13+
Asenna MathCAT NVDA:n lisäosakaupasta tai [NVDA:n Internet-lisäosakaupasta](https://nvda-addons.org/addon.php?id=272).
14+
15+
## Käytän JAWS-ruudunlukijaa
16+
17+
MathCAT tulee JAWS-ruudunlukijan mukana. Sinun ei tarvitse asentaa sitä erikseen.
18+
19+
## Aloita MathCATin käyttö NVDA:lla
20+
21+
Käytä ruudunlukijaasi tuttuun tapaan nettisivulla tai e-kirjassa. Kun kohtaat matemaattista sisältöä, joka on kirjoitettu MathML-koodilla, ruudunlukijasi lukee sen ääneen automaattisesti.
22+
23+
Jos haluat tutustua esimerkiksi matemaattisen kaavan yksityiskohtiin, niin voit käyttää navigointitilaa painamalla välilyönti-näppäintä tai näppäinkomentoa NVDA-näppäin+Alt+M. Jos haluat poistua navigointitilasta, paina Esc-näppäintä.
24+
25+
### Yleisimmät näppäinkomennot
26+
27+
- Voit liikkua oikealle, vasemmalle, ylös ja alas -suunnissa käyttämällä nuolinäppäimiä.
28+
- Voit liikkua taulukon soluissa Ctrl+nuolinäppäimet.
29+
- Voit siirtyä matemaattisen sisällön alkuun Home-näppäimellä ja loppuun End-näppäimellä.
30+
- Voit kuulla nykyisen sijaintisi painamlla välilyönti-näppäintä.
31+
- Voit muuttaa navigointitilaa painamalla Vaihto+Nuoli ylös/Nuoli alas. Lue lisää kohdasta: [Navigaatio](#navigaatio).
32+
33+
Kun siirryt navigaatiotilaan, niin voit kopioida kyseisen osan matemaattisesta sisällöstä MathML-koodina painamalla Ctrl+c.
34+
35+
Navigointiin on monia eri näppäinkomentoja. Voit lukea kaikki: [Kaikki navigaatiokomennot](#kaikki-navigaatiokomennot).
36+
37+
### MathCATin asetukset
38+
39+
MathCATissä on erilaisia asetuksia, joita säätämällä saat sen itsellesi sopivaksi. Pääset asetuksiin näppäinkomennolla NVDA-näppäin+n, sitten Asetukset ja sitten MathCATin asetukset. Asetuksissa voi valita Puhe, Navigaatio ja Pistekirjoitus.
40+
41+
#### Puhe
42+
43+
Vot säätää seuraavat asetukset puheelle. Jokaisen asetuksen alla on sen kaikki vaihtoehdot lyhyellä kuvauksella. Oletusasetukset on kirjoitettu hakasulkeisiin.
44+
45+
- Vamma:
46+
- \[Sokeus.\] Puhe on yksikäsitteistä.
47+
- Heikkonäköisyys. Puhetta on vähemmän.
48+
- Oppimisvaikeus. Puhetta on vähemmän.
49+
- Kieli:
50+
- \[Käytä puheäänen kieltä (automaattinen)\]
51+
- Englanti (en)
52+
- Espanja (es)
53+
- Suomi (fi)
54+
- Indonesia (id)
55+
- Italia (it)
56+
- Ruotsi (sv)
57+
- Vietnami (vi)
58+
- Kiina, perinteinen (zh-tw)
59+
- Puhetyyli:
60+
- \[ClearSpeak.\] Matemaattinen sisältö puhutaan, kuten opettaja puhuisi luokkahuoneessa.
61+
- SimpleSpeak. Matemaattinen sisältö puhutaan lyhyemmin. Puhe ei ole aina yksikäsitteistä.
62+
- Puheen määrä:
63+
- Harva. Tiettyjä sanoja on lyhennetty, kuten "logaritmi" on "log".
64+
- \[Keskitaso.\] Harvan ja runsaan välillä.
65+
- Runsas. Kaikki puhutaan ääneen. Luenta on yksikäsitteinen.
66+
- Puheen suhteellinen nopeus:
67+
- \[100\]. Nopeus muuttuu suhteessa ruudunlukijan asetettuun puhenopeuteen. Luku on prosenteissa ja nopeutta voi muuttaa välillä 1 ja 1000. 100 tarkoittaa samaa nopeutta, vähemmän tarkoittaa hitaampaa ja suurempi nopeampaa.
68+
- Taukokerroin:
69+
- \[1\]. Arvot ovat välillä 0 ja 10. Säätää, miten pitkiä taukoja matemaattisen sisällön eri osien välillä on.
70+
- Toista äänimerkki, kun matemaattisen sisällön puhuminen aloitetaan/lopetetaan
71+
- \[Ei ääntä.\]
72+
- Äänimerkki.
73+
- Kemiallisten kaavojen puhuminen:
74+
- \[Tavaaminen.\] Kemialliset kaavat luetaan kirjain kirjaimelta, esimerkiksi H2O luetaan H kaksi O.
75+
- Pois käytöstä. H2O luetaan H ala 2 O.
76+
77+
#### Navigaatio
78+
79+
MathCATin avulla voit siirtyä yksityiskohtaisesti matemaattisen sisällön sisällä. Voit kuunnella sen kokonaan, osissa tai liikkua edestakaisin esimerkiksi kaavassa. Voit määrittää asetuksissa, kuinka tämä tehdään ja miten yksityiskohtaista tietoa haluat.
80+
81+
Jokaisen asetuksen alla on sen kaikki vaihtoehdot lyhyellä kuvauksella. Oletusasetukset on kirjoitettu hakasulkeisiin.
82+
83+
- Navigointitila, kun siirryt matemaattiseen sisältöön:
84+
- \[Laajennettu.\] Voit liikkua matemaattisesti merkittävien osien välillä. Esimerkiksi osoittaja, nimittäjä, eksponentti, suluissa oleva lauseke.
85+
- Yksinkertainen. Voit liikkua sanojen välillä, mutta jos kohtaat lausekkeen (esimerkiksi neliöjuuren), se luetaan kokonaan ääneen.
86+
- Merkki. Voit liikkua sanojen tai lukujen välillä. Voit siirtyä yksityiskohtaisemmalle tasolle, jolla voit lukea kirjain kirjaimelta tai numero numerolta.
87+
88+
Voit muuttaa navigointitilan laajemmaksi matemaattisen sisällön sisällä näppäinkomennolla Shift+Nuoli ylös, jolloin tyyli muuttuu Yksinkertaisesta Laajennetuksi (tai Merkki -tyylistä Yksinkertaiseksi).
89+
90+
Voit muuttaa navigointitilan yksityiskohtaisemmaksi näppäinkomennolla Shift+Nuoli alas, jolloin tyyli muuttuu Laajennetusta Yksinkertaiseksi (tai Yksinkertaisesta Merkki -tyyliin). "Ylös" tarkoittaa laajempaa kuvailua ja "alas" tarkoittaa tarkempaa kuvailua.
91+
92+
Voit painaa valintaruutua, jolla voit valita, mikä navigointityyli on oletuksena, kun palautat tyylin ennalleen. Oletuksena mitään tiettyä navigointityyliä ei ole valittu.
93+
94+
- Navigointipuheen tyyli, kun aloitat lausekkeessa navigoimisen:
95+
- \[Puhu.\] Lukee sen kohdan matemaattisesta sisällöstä ääneen, jossa tällä hetkellä olet.
96+
- Kuvailu/anna yhteenveto. Antaa laajemman kuvailun koko valitusta sisällöstä.
97+
98+
Voit painaa valintaruutua, jolla voit valita, nollaanko navigointipuheen tyyli, kun siirryt uuteen lausekkeeseen. Se on oletuksena valittuna.
99+
100+
- Puheen määrä navigoitaessa:
101+
- Harva. Tiettyjä sanoja on lyhennetty, kuten "logaritmi" on "log".
102+
- \[Keskitaso.\] Harvan ja runsaan välillä.
103+
- Runsas. Kaikki puhutaan ääneen. Luenta on yksikäsitteinen.
104+
105+
#### Pistekirjoitus
106+
107+
Voit valita pistekirjoitusasetukset seuraavista vaihtoehdoista. Oletusasetus on hakasuluissa.
108+
109+
- Matematiikan pistekirjoitus:
110+
- CMU.
111+
- Nemeth.
112+
- Ruotsalainen.
113+
- UEB.
114+
- Vietnamilainen.
115+
- Korosta nykyinen navigaatiokohta pisteillä 7 ja 8:
116+
- Pois päältä.
117+
- Ensimmäinen merkki. Matemaattisen sisällön ensimmäinen merkki on korostettu.
118+
- Päätepisteet. Matemaattisen sisällön ensimmäinen ja viimeinen merkki ovat korostettuja.
119+
- Kaikki. Koko matemaattinen sisältö on korostettu.
120+
121+
Korostus riippuu navigaatiotilan tarkkuudesta. Korostus voi olla koko matemaattisen sisällön alueella tai yksityiskohtaisempana esimerkiksi murtoluvun alussa.
122+
123+
### Kaikki navigaatiokomennot
124+
125+
Taulukossa on esitetty kaikki komennot, joita voit käyttää matemaattisessa sisällössä liikkumiseen. Ensimmäisessä sarakkeessa on näppäimen nimi. Toisessa sarakkeessa kerrotaan, mitä tapahtuu, jos painat vain kyseistä näppäintä. Kolmannessa sarakkeessa kerrotaan, mitä tapahtuu, jos painat näppäinkomentona Ctrl-näppäintä ja kyseistä näppäintä. Neljännessä sarakkeessa kerrotaan, mitä tapahtuu, jos painat näppäinkomentona Vaihto-näppäintä ja kyseistä näppäintä. Viidennessä sarakkeessa kerrotaan, mitä tapahtuu, jos painat näppäinkomentona Ctrl- ja Vaihto-näppäimiä ja kyseistä näppäintä.
126+
127+
Sarakematematiikalla tarkoitetaan matemaattista sisältöä, joka esitetään taulukkona, kuten matriisit, yhtälöparit tai -ryhmät. Niitä voi navigoida kuten taulukoita.
128+
129+
| Näppäin | Pelkästään | \+ Ctrl | \+ Vaihto | \+ Ctrl + Vaihto |
130+
| --- | --- | --- | --- | --- |
131+
| Nuoli vasen | Siirry edelliseen. | Taulukossa: siirry edelliseen soluun. Sarakematematiikassa: siirry edelliseen numeroon. Huomaa: Ctrl+Alt+Nuoli vasen toimii myös. | Lue edellinen. | Kuvaile edellinen. |
132+
| Nuoli oikea | Siirry seuraavaan | Taulukossa: siirry seuraavaan soluun. Sarakematematiikassa: siirry seuraavaan numeroon. Huomaa: Ctrl+Alt+Nuoli oikea toimii myös. | Lue seuraava. | Kuvaile seuraava. |
133+
| Nuoli ylös | Siirry yleisemmälle tasolle. | Taulukossa: siirry sarakkeessa yksi solu ylöspäin. Sarakematematiikassa: siirry sarakkeessa yksi numero ylöspäin. Huomaa: Ctrl+Alt+Nuoli ylös toimii myös. | Muuta navigointitilaa (Laajennettu, Yksinkertainen, Merkki) yleisemmäksi. | Siirry uloimmalle tasolle (uloin taso). |
134+
| Nuoli alas | Siirry yksityiskohtaisemmalle tasolle. | Taulukossa: siirry sarakkeessa yksi solu alaspäin. Sarakematematiikassa: siirry sarakkeessa numero alaspäin. Huomaa: Ctrl+Alt+Nuoli alas toimii myös. | Muuta navigointitilaa (Laajennettu, Yksinkertainen, Merkki) tarkemmaksi. | Siirry yksityiskohtaisimmalle tasolle (sisin taso). |
135+
| Enter | Missä olen. | Missä olen (globaali). | | |
136+
| Numeronäppäimet 1-10 (0 on 10) | Siirry paikkamerkkiin. | Aseta paikkamerkki. | Lue paikkamerkki. | Kuvaile paikkamerkki. |
137+
| Välilyönti | Lue nykyinen. | Lue nykyinen solu. | Vaihda "puhetyyliä" tyyliin lue tai kuvaile. | Kuvaile nykyinen. |
138+
| Home | Siirry matemaattisen sisällön alkuun. | Siirry rivin alkuun. | Taulukossa: Siirry sarakkeen alkuun. Sarakematematiikassa: Siirry sarakkeen alkuun. | |
139+
| End | Siirry matemaattisen sisällön loppuun. | Siirry rivin loppuun. | Taulukossa: Siirry sarakkeen loppuun. Sarakematematiikassa: Siirry sarakkeen loppuun. | |
140+
| Askelpalautin (backspace) | Siirry takaisin edelliseen sijaintiin. | | | |

‎docs/users.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
layout: default
3+
lang: en
4+
ref: users
5+
---
16
# <img src="logo.png" style="position: relative; top: 16px; z-index: -1;" alt="MathCAT logo"> User Guide
27

38
## Advice on Choosing a Voice

0 commit comments

Comments
 (0)