OmniRoute/docs/i18n/fi/docs/I18N.md

i18n — Internationalization Guide (Suomi)

🌐 Languages: 🇺🇸 English · 🇪🇸 es · 🇫🇷 fr · 🇩🇪 de · 🇮🇹 it · 🇷🇺 ru · 🇨🇳 zh-CN · 🇯🇵 ja · 🇰🇷 ko · 🇸🇦 ar · 🇮🇳 hi · 🇮🇳 in · 🇹🇭 th · 🇻🇳 vi · 🇮🇩 id · 🇲🇾 ms · 🇳🇱 nl · 🇵🇱 pl · 🇸🇪 sv · 🇳🇴 no · 🇩🇰 da · 🇫🇮 fi · 🇵🇹 pt · 🇷🇴 ro · 🇭🇺 hu · 🇧🇬 bg · 🇸🇰 sk · 🇺🇦 uk-UA · 🇮🇱 he · 🇵🇭 phi · 🇧🇷 pt-BR · 🇨🇿 cs · 🇹🇷 tr

---

OmniRoute tukee30 kieltätäydellä kojelaudan käyttöliittymäkäännöksellä, käännetyllä dokumentaatiolla ja arabian ja heprean RTL-tuella.## Quick Reference

Tehtävä	Komento
Luo käännöksiä	node scripts/i18n/generate-multilang.mjs messages
Käännä asiakirjat (LLM)	python3 scripts/i18n_autotranslate.py --api-url <url> --api-key <avain> --malli <malli>
Vahvista alue	python3 scripts/validate_translation.py quick -l cs
Tarkista koodiavaimet	python3 scripts/check_translations.py
Luo laadunvarmistusraportti	node scripts/i18n/generate-qa-checklist.mjs
Visual QA (näytelmäkirjailija)	node scripts/i18n/run-visual-qa.mjs	## Arkkitehtuuri

Source of Truth

-Käyttöliittymän merkkijonot: src/i18n/messages/en.json (englanninkielinen lähde, ~2800 avainta) -Kielitiedostot: src/i18n/messages/{locale}.json (30 käännöstä) -Framework: "next-intl" evästepohjaisella kielitarkkuudella -Config: src/i18n/config.ts — määrittää kaikki 30 aluetta, kielten nimeä ja lippua### Runtime Flow

1. Käyttäjä valitsee kielen → NEXT_LOCALE evästesarja
2. src/i18n/request.ts ratkaisee kieli-asetuksen: eväste → Accept-Language-otsikko → vara-fi
3. Dynaaminen tuonti lataa tiedoston "messages/{locale}.json".
4. Komponentit käyttävät useTranslations("namespace") ja t("key")### Supported Locales

Koodi	Kieli	RTL	Google-kääntäjän koodi
"ar"	العربية	Kyllä	"ar"
"bg"	Български	Ei	"bg"
cs	Čeština	Ei	cs
"da"	Dansk	Ei	"da"
de	Deutsch	Ei	de
"es"	Español	Ei	"es"
"fi"	Suomi	Ei	"fi"
"fr"	Français	Ei	"fr"
"hän"	עברית	Kyllä	"iw"
hei	हिन्दी	Ei	hei
hu	Magyar	Ei	hu
"id"	Bahasa Indonesia	Ei	"id"
"se"	Italiano	Ei	"se"
"ja"	日本語	Ei	"ja"
"ko"	한국어	Ei	"ko"
ms	Bahasa Melayu	Ei	ms
"nl"	Alankomaat	Ei	"nl"
"ei"	Norsk	Ei	"ei"
"phi"	filippiiniläinen	Ei	tl
"pl"	Polski	Ei	"pl"
pt	Português (Portugali)	Ei	pt
"pt-BR"	Português (Brasilia)	Ei	pt
"ro"	Română	Ei	"ro"
"ru"	Русский	Ei	"ru"
"sk"	Slovenčina	Ei	"sk"
"sv"	Svenska	Ei	"sv"
"th"	ไทย	Ei	"th"
tr	Türkçe	Ei	tr
"uk-UA"	Українська	Ei	"uk"
"vi"	Tiếng Việt	Ei	"vi"
"zh-CN"	中文 (简体)	Ei	"zh-CN"	## Adding a New Language

1. Register the Locale

Muokkaa src/i18n/config.ts:```ts // Add to LOCALES array "xx", // Add to LANGUAGES array { code: "xx", label: "XX", name: "Language Name", flag: "🏳️" },

### 2. Add to Generator

Muokkaa `scripts/i18n/generate-multilang.mjs` — lisää merkintä kohtaan `LOCALE_SPECS':```js
{
  code: "xx",
  googleTl: "xx",
  label: "XX",
  flag: "🏳️",
  languageName: "Language Name",
  readmeName: "Language Name",
  docsName: "Language Name",
},

3. Generate Initial Translation

node scripts/i18n/generate-multilang.mjs messages

Tämä luo src/i18n/messages/xx.json-tiedoston, joka käännetään automaattisesti en.json-tiedostosta Google-kääntäjän kautta.### 4. Review & Fix Auto-Translations

Automaattiset käännökset ovat lähtökohta. Tarkista manuaalisesti:

• Tekninen tarkkuus
• Kontekstin mukainen terminologia
• Paikkamerkkien oikea käsittely ("{count}", "{value}" jne.)### 5. Validate

python3 scripts/validate_translation.py quick -l xx
python3 scripts/validate_translation.py diff common -l xx

6. Generate Translated Documentation

node scripts/i18n/generate-multilang.mjs docs

Auto-Translation Pipeline

generate-multilang.mjs (Google Translate)

Ensisijainen automaattinen käännöskone— käyttää Google Kääntäjän ilmaista sovellusliittymää käännösten luomiseen käyttöliittymämerkkijonoille, README:ille ja dokumentaatiolle.```bash node scripts/i18n/generate-multilang.mjs [messages|readme|docs|all]

| Tila | Mitä se tekee |
| ----------- | ------------------------------------------------------------------------------ |
| "viestit" | Kääntää puuttuvat avaimet tiedostosta `src/i18n/messages/{locale}.json` en.jsonista |
| "lue minut" | Kääntää `README.md` kaikille kielille muodossa `README.{code}.md` projektin juuressa |
| "asiakirjat" | Kääntää `DOC_SOURCE_FILES` `docs/i18n/{locale}/{docName}` |
| "kaikki" | Suorittaa kaikki kolme tilaa |

**Ominaisuudet:**

-**Tekstin suojaus**: Peittää koodilohkot (` ``` `), rivikoodin (`` ` ``), merkintälinkit/kuvat (`[teksti](url)`), HTML-tunnisteet, taulukot ja ICU-paikkamerkit (`{count}`, `{arvo}`, `{total}` jne.) ennen käännöstä ja palauttaa ne sitten
-**Pakattu erä**: Yhdistää useita merkkijonoja `__OMNIROUTE_I18N_SEPARATOR__` erottimilla API-kutsujen minimoimiseksi (enintään 1800 merkkiä per pyyntö)
-**Muistissa oleva välimuisti**: Välttää ylimääräiset API-kutsut toistuville merkkijonoille istunnon aikana
-**Uudelleenyrityslogiikka**: eksponentiaalinen peruutus (enintään 5 yritystä 300 ms × yritysviiveellä) 429/5xx-virheille
-**Aikakatkaisu**: 20 sekuntia per pyyntö
-**Ohita olemassa oleva**: Jos kohdetiedosto on jo olemassa, sitä EI kirjoiteta päälle

**Tärkeät käytöstavat:**

- `docs/i18n/README.md`**luonnetaan uudelleen**joka ajo – se on automaattisesti luotu hakemisto kaikista asiakirjoista
- Juuri `README.{code}.md` -tiedostot luodaan vain, jos niitä ei ole olemassa (ohittaa kieliasetukset `EXISTING_README_CODES`)
- Kielipalkit (`🌐**Kielet:**...`) lisätään/päivitetään automaattisesti kaikkiin käännetyihin asiakirjoihin### i18n_autotranslate.py (LLM-based)

**Toissijainen kääntäjä**— käyttää mitä tahansa OpenAI-yhteensopivaa LLM-sovellusliittymää (mukaan lukien itse OmniRoute) olemassa olevien "docs/i18n/" -merkintätiedostojen kääntämiseen. Paras asiakirjojen kiillottamiseen tai kääntämiseen uudelleen laadukkaammin kuin Google-kääntäjä.```bash
python3 scripts/i18n_autotranslate.py \
  --api-url http://localhost:20128/v1 \
  --api-key sk-your-key \
  --model gpt-4o

Ominaisuudet:

• Tarkistaa docs/i18n/ -merkintätiedostot englanninkielisten kappaleiden varalta
• Ohittaa koodilohkot, taulukot ja jo käännetyn sisällön
• Lähettää kappaleita LLM:lle teknisen käännösjärjestelmän kehotteen avulla
• Tukee kaikkia 30 kieltä## Validation & QA

validate_translation.py

Käännösten tarkistaja– vertaa mitä tahansa kielen JSON-muotoa en.jsoniin ja raportoi ongelmista.```bash

Quick check (counts only)

python3 scripts/validate_translation.py quick -l cs

Output:

Missing: 0

Untranslated: 0

Ignored (UNTRANSLATABLE_KEYS): 236

Detailed diff by category

python3 scripts/validate_translation.py diff common -l cs python3 scripts/validate_translation.py diff settings -l cs

Export to CSV

python3 scripts/validate_translation.py csv -l cs > report.csv

Export to Markdown

python3 scripts/validate_translation.py md -l cs > report.md

Full report (default)

python3 scripts/validate_translation.py -l cs

**Tunnistaa:**

-**Puuttuvat avaimet**— avaimet en.json-tiedostossa, mutta eivät aluetiedostossa
-**Lisäavaimet**— avaimet maa-asetustiedostossa, mutta eivät en.json-tiedostossa
-**Kääntämättömät avaimet**– avaimet, joiden kieli-arvo vastaa englanninkielistä lähdettä (lukuun ottamatta sallittujen luetteloa)
-**Paikkamerkkien yhteensopimattomuudet**— ICU-paikkamerkit, jotka eivät täsmää lähteen ja käännöksen välillä

**Poistumiskoodit:**
| Koodi | Merkitys |
|------|---------|
| 0 | OK |
| 1 | Yleinen virhe |
| 2 | Puuttuvat merkkijonot (kova virhe) |
| 3 | Kääntämätön varoitus (pehmeä) |

**Ympäristö:**Aseta TRANSLATION_LANG=cs tai käytä -l cs -lippua.### check_translations.py

**Code-to-JSON-avaintarkistus**– etsii src/**/*.tsx- ja src/**/*.ts-kutsuja useTranslations()-kutsujen varalta ja varmistaa, että kaikki viitatut avaimet ovat olemassa en.json-tiedostossa.```bash
# Basic check
python3 scripts/check_translations.py

# Verbose output
python3 scripts/check_translations.py --verbose

# Auto-fix (adds missing keys to en.json)
python3 scripts/check_translations.py --fix

generate-qa-checklist.mjs

Staattinen analyysi QA— skannaa Next.js-sivutiedostot i18n-riskimittareiden varalta ja luo Markdown-raportin.```bash node scripts/i18n/generate-qa-checklist.mjs

**Shekit:**

- Kiinteän leveyden luokan käyttö (ylivuotoriski)
- Suuntaus vasen/oikea luokat (RTL-riski)
- Leikkaukseen alttiita kuvioita
- Kieli-asetus (puuttuvat/ylimääräiset avaimet vs. en.json)
- README-kielen valintapalkit tärkeysjärjestyskohteissa ("es", "fr", "de", "ja", "ar")

**Tuloste:**`docs/reports/i18n-qa-checklist-{date}.md`### run-visual-qa.mjs

**Visuaalinen laadunvarmistus Playwrightin**kautta — ottaa kuvakaappauksia kaikista kojelautareiteistä useilla eri kielialueilla ja näyttöporteissa ja arvioi sitten sivun kunnon.```bash
# Default: es, fr, de, ja, ar on localhost:20128
node scripts/i18n/run-visual-qa.mjs

# Custom base URL and locales
QA_BASE_URL=http://staging.example.com QA_LOCALES=de,fr node scripts/i18n/run-visual-qa.mjs

# Custom routes
QA_ROUTES=/dashboard/settings,/dashboard/providers node scripts/i18n/run-visual-qa.mjs

Tunnistaa:

• Tekstin ylivuoto
• Elementtien leikkaus
• RTL-asettelu ei täsmää

Tuloste:docs/reports/i18n-visual-qa-{date}.md + JSON-raportti## Managing Untranslatable Keys

untranslatable-keys.json

Tiedosto:scripts/i18n/untranslable-keys.json

Sallitut avaimet, joiden tulee pysyä identtisinä englanninkielisen lähteen kanssa. validate_translation.py käyttää sitä välttääkseen vääriä positiivisia "kääntämättömiä" varoituksia.```json { "description": "Keys that should remain untranslated...", "keys": [ "common.model", "common.oauth", "health.cpu", ... ] }

**Mikä tänne kuuluu:**

- Tuotemerkkien/tuotteiden nimet: `landing.brandName`, `common.social-github`
- Tekniset termit/lyhenteet: "health.cpu", "mcpDashboard.pid", "settings.ai"
- ICU-/muotomerkkijonot: "apiManager.modelsCount", "health.millisecondsShort"
- Paikkamerkkiarvot: "providers.openaiBaseUrlPlaceholder", "cliTools.baseUrlPlaceholder"
- Protokollan nimet: "common.http", "common.oauth", "providers.oauth2Label"
- Navigointiosat: "sidebar.primarySection", "sidebar.cliSection"

**Avaimen lisääminen:**Muokkaa avaimet-taulukkoa tiedostossa scripts/i18n/untranslable-keys.json ja suorita vahvistus uudelleen.## CI Integration

### GitHub Actions (`.github/workflows/ci.yml`)

CI-liukuhihna vahvistaa kaikki alueet jokaisella painalluksella ja PR:lla:

1.**`i18n-matrix` työ**— löytää dynaamisesti kaikki kieliasetukset (pois lukien en.json)
2.**`i18n` job**— suorittaa `validate_translation.py quick -l '<lang>'` jokaiselle maa-alueelle rinnakkain
3.**`ci-summary` -työ**— kokoaa tulokset kojelaudan yhteenvedoksi```yaml
# i18n-matrix: discovers languages
LANGS=$(ls src/i18n/messages/*.json | xargs -n1 basename | sed 's/.json$//' | grep -v '^en$')

# i18n: validates each language
python3 scripts/validate_translation.py quick -l '${{ matrix.lang }}'

Kojelaudan lähtö:```

🌍 Translations

Metric	Value
Languages checked	30
Total untranslated	0

✅ All translations complete

## File Structure

src/i18n/ ├── config.ts # Locale definitions (30 locales, RTL config) ├── request.ts # Runtime locale resolution └── messages/ ├── en.json # Source of truth (~2800 keys) ├── cs.json # Czech translation ├── de.json # German translation └── ... # 30 locale files total

scripts/ ├── i18n/ │ ├── generate-multilang.mjs # Auto-translation engine (Google Translate, 888 lines) │ ├── generate-qa-checklist.mjs # Static analysis QA │ ├── run-visual-qa.mjs # Playwright visual QA │ └── untranslatable-keys.json # Allowlist for validation (236 keys) ├── validate_translation.py # Translation validator ├── check_translations.py # Code-to-JSON key checker └── i18n_autotranslate.py # LLM-based doc translator

.github/workflows/ └── ci.yml # i18n validation in CI matrix

docs/ ├── I18N.md # This file — i18n toolchain documentation ├── i18n/ │ ├── README.md # Auto-generated language index │ ├── cs/ # Czech docs │ │ └── docs/ │ │ ├── I18N.md # Czech translation of this file │ │ └── ... │ ├── de/ # German docs │ └── ... # 30 locale directories └── reports/ ├── i18n-qa-checklist-.md # Static analysis reports └── i18n-visual-qa-.md # Visual QA reports

## Best Practices

### When Editing Translations

1.**Muokkaa aina ensin en.json-tiedostoa**– se on totuuden lähde
2.**Suorita `generate-multilang.mjs messages`**levittääksesi uudet avaimet kaikille kielille
3.**Tarkista automaattiset käännökset**— Google-kääntäjä on lähtökohta, ei lopullinen
4.**Tarkista ennen sitoutumista**— `python3 scripts/validate_translation.py quick -l <lang>`
5.**Päivitä "untranslable-keys.json"**, jos avain pysyy englanninkielisenä### Placeholder Safety

- ICU-paikkamerkit (`{count}`, `{value}`, `{total}`, `{seconds}`) on säilytettävä tarkasti
- Monikkomuotojen (`{count, plural, one {# model} other {# model}}`) on säilytettävä rakenne
- Validaattori havaitsee paikkamerkkien yhteensopimattomuudet automaattisesti### Adding New Translation Keys in Code

```tsx
// Use namespaced keys
const t = useTranslations("settings");
t("cacheSettings"); // maps to settings.cacheSettings in JSON

// Run check_translations.py to verify keys exist
python3 scripts/check_translations.py --verbose

RTL Considerations

• Arabia (ar) ja heprea (he) ovat RTL-alueita
• Vältä kovakoodattua "vasenta"/"oikeaa" CSS:ää - käytä "alku"/"loppu" loogisia ominaisuuksia
• Visuaalinen laadunvarmistus havaitsee RTL-asettelun epäsuhtaudet "run-visual-qa.mjs" -komennolla## Known Issues & History

in.json → hi.json Fix

Generaattori käytti alun perin hindin kielessä koodia: "in" (vanhentunut Google-kääntäjäkoodi) oikean ISO 639-1 "hi" sijaan. Tämä loi orvoksi jääneen in.json-kopion tiedostosta "hi.json". Korjattu muuttamalla "code: "in"" muotoon "code: "hi" tiedostossa "generate-multilang.mjs" ja poistamalla orpotiedosto.### docs/i18n/README.md Is Auto-Generated

docs/i18n/README.md-tiedosto generate-multilang.mjs docs luo kokonaan uudelleen. Kaikki manuaaliset muokkaukset menetetään. Käytä tiedostoa "docs/I18N.md" (tämä tiedosto) käsinkirjoitettuun dokumentaatioon, jonka pitäisi säilyä.### External Untranslatable Keys List

Sallittu untranslable-keys.json-luettelo siirrettiin valiidate_translation.py-tiedoston sisäisestä Python-joukosta ulkoiseen JSON-tiedostoon ylläpidon helpottamiseksi. Validaattori lataa sen ajon aikana.### generate-multilang.mjs Hindi Code Fix

Generaattori käytti alun perin hindin kielessä koodia: "in" (vanhentunut Google-kääntäjäkoodi) oikean ISO 639-1 "hi" sijaan. Diegosouzapw esitteli tämän alkuvirran commitissa "952b0b22c". Korjattu muuttamalla 'code: "in"" muotoon "code: "hi" 'LOCALE_SPECS' -taulukossa ja poistamalla orpo "in.json"-tiedosto.### validate_translation.py Ignored Count Output

Pikatarkistus näyttää nyt ohitettujen avainten määrän tiedostosta "untranslable-keys.json":``` Missing: 0 Untranslated: 0 Ignored (UNTRANSLATABLE_KEYS): 236