i18n-core

Sisällysluettelo

[TOC]

Tavoite

Keskeinen moduuli, joka hallitsee kieliversioita, käännöksiä ja niiden statuksia.

Tavoite on luoda keskeinen moduuli, joka hallitsee kieliversioita, käännöksiä ja niiden statusseja. Tämä moduuli tarjoaa:

• Käännösten hallinta: Mahdollisuus käyttää käännöksiä eri kielillä sovelluksessa, joko master- tai fallback-kielellä.
• Käännösstatus: Seuraa, onko käännös tehty, onko käännös puutteellinen, ja mahdollistaa käännösten päivittämisen ja ylläpidon.
• Kieliversion hallinta: Käytettävissä oleva kieli voidaan vaihtaa ja sen mukaan sovelluksen tekstit näkyvät oikeilla kielillä.
• Käännösten flättäys (flattening): Flättää monikieliset JSON-rakenteet yksinkertaisiksi avain-arvo-pareiksi, joita voi käyttää käännösjärjestelmässä (esim. i18next tai muu järjestelmä).

Toiminnot

• Kieliversion valinta ja hallinta.
• Käännösten flättäys.
• Fallback-kielihallinta, jos käännös puuttuu.
• Käännösstatus, kuten puuttuva, valmiiksi käännetty ja osittain käännetty.
• Exportoi ja importoi käännökset eri moduuleihin, jotta muut moduulit voivat käyttää niitä.

Rajapinta

• API käännöksille ja kieliversion hallinnalle.
• Käännösten status: voimme tarkastella, missä käännöksissä on ongelmia ja päivittää niitä.
• Moduulirajapinta muiden moduulien käyttöön: i18n-react ja muut front-endin komponentit käyttävät tätä moduulia käännösten lataamiseen ja näyttämiseen.

Testaus

• Testataan, että käännösten flättäys toimii oikein eri kielillä.
• Testataan, että fallback-kielituki toimii, jos käännöstä ei ole.
• Testataan, että käännösstatus-päivitykset toimivat oikein.

Repo-rakenne

i18n-core/
│
├── src/
│   ├── index.ts                 # Moduulin päähakemisto (yksi pääexportti)
│   ├── i18n.ts                  # Kieliversion hallinta ja käännöksien logiikka
│   ├── language-status.ts       # Käännösstatusten hallinta
│   ├── dayjsLocale.ts           # Day.js - Locale-hallinta
│   ├── translation-status.ts    # Käännösstatuksen käsittely ja tallentaminen
│   └── utils/                   # Yhteiset apu- ja util-tiedostot
│       ├── flattenTranslations.ts # Käännösten litistämistoiminnot
│       ├── getLanguageCodes.ts  # Kielikoodien ja masterkielen haku
│       └── constants.ts         # Yhteiset vakioarvot ja käännöksen avaimet
│
├── package.json                 # Moduulin metatiedot ja riippuvuudet
├── tsconfig.json                # TypeScript-konfiguraatio
├── README.md                    # Dokumentaatio ja käyttöohjeet
└── tests/                       # Testikansio
    ├── i18n.test.ts             # Testit moduulin toiminnoille
    ├── language-status.test.ts  # Testit käännösstatuksen hallinnalle
    └── translation-status.test.ts # Testit käännösstatuksen käsittelyyn

Tiedostojen ja kansioiden kuvaus

1. src/index.ts:
   • Tämä tiedosto on pääexportti, joka yhdistää kaikki moduulin toiminnot ja vie ne ulospäin.
2. src/i18n.ts:
   • Tässä tiedostossa hallitaan kieliversioiden asetuksia ja niiden lataamista.
   • Vastuussa masterkielistä ja fallback-kielistä.
   • Esimerkiksi voidaan toteuttaa getMasterLanguage() ja getFallbackLanguages() -funktiot.
3. src/language-status.ts:
   • Tässä tiedostossa käsitellään kieliversion tilan hallintaa.
   • Se voi sisältää logiikkaa, jolla tarkistetaan, onko käännöksen tila “OK”, “Puuttuu” jne.
4. src/dayjsLocale.ts:
   • Käytetään päivämäärien ja aikojen näyttämiseen eri kielillä Day.js-kirjaston avulla.
   • Päivämäärämuotoilu- ja kielisidonnaiset asetukset.
5. src/translation-status.ts:
   • Vastaa käännösstatuksen säilyttämisestä ja hallinnasta.
   • Esimerkiksi varmistetaan, että käännökset synkronoituvat masterkielen kanssa ja että oikea kieliversio on aktiivinen.
6. src/utils/flattenTranslations.ts:
   • Tämä apufunktio litistää monikielisen JSON-rakenteen niin, että käännösjärjestelmät (kuten i18next) voivat käyttää sitä suoraan.
7. src/utils/getLanguageCodes.ts:
   • Palvelu, joka palauttaa kaikki kielikoodit, jotka ovat määritetty i18n-core-moduulille.
8. src/utils/constants.ts:
   • Yhteiset vakioarvot ja käännöksen avaimet (esim. kielikoodit, masterkieli, fallback).
9. package.json:
   • Sisältää moduulin metatiedot, riippuvuudet ja skriptit.
10. tsconfig.json:
    • TypeScriptin asetukset.
11. tests/:
    • Testikansio, jossa on yksikkötestit moduulin toiminnoille.
    • Esimerkiksi:
      • i18n.test.ts testaa kieliversioiden lataamista ja hallintaa.
      • language-status.test.ts testaa kieliversion statuksia.
      • translation-status.test.ts testaa käännösten statuksia ja validointia.

Seuraavat Askeleet

1. Projekti ja alkuperäiset asetukset:
   • Suorita pnpm init ja luo tarvittavat package.json ja tsconfig.json -tiedostot.
   • Asenna kaikki riippuvuudet, kuten typescript, dayjs, ts-node ja mahdollisesti muut tarvittavat kirjastot
2. Toteuta perusmoduulin rakenne:
   • Luo i18n.ts, language-status.ts, translation-status.ts ja utils/ -hakemisto.
   • Alusta tiedostot yksinkertaisilla funktioilla, jotka suorittavat perustoiminnot, kuten käännösten hakeminen ja palautus.
3. Testit:
   • Lisää yksikkötestejä kaikille tärkeille toiminnoille.
   • Varmista, että kieliversioiden ja käännösstatusten käsittely toimii oikein.
4. Dokumentointi:
   • Lisää alkukommentit jokaiseen tiedostoon ja toiminnon kuvaukset.
   • Lisää README.md-tiedostoon käyttöohjeet ja esimerkkejä moduulin käytöstä.

Tässä on perusrunko, jonka avulla voit aloittaa i18n-core-moduulin toteuttamisen ja laajentaa sitä tarpeen mukaan. Jos tarvitset apua jonkin osa-alueen kanssa, voin auttaa tarkemmin.

i18n-core-moduulin kuvaus

Kuvaus:

i18n-core on keskeinen moduuli, joka hallitsee kieliversioiden ja käännösten hallintaa. Se tarjoaa rajapinnan käännöksille ja tukee dynaamista kieliversion valintaa. Moduuli tukee master-kielen fallbackia, käännösten lataamista ja käännösten tilan hallintaa. Käännöksiä voidaan käyttää sekä frontendissä (React) että backendissä, ja ne voivat olla joko staattisia JSON-tiedostoja tai dynaamisesti ladattuja tiedostoja.

Moduulin tarjoamat palvelut:

1. Käännösten hakeminen: Hakee käännöksiä määritetyltä kieleltä, ja jos käännös puuttuu, käyttää fallback-kieltä (esim. master-kieli).
2. Kieliversion hallinta: Määrittää aktiiviset kielet ja tukee master-kielen määrittämistä.
3. Käännösten lataaminen: Lataa käännöksiä dynaamisesti JSON-tiedostoista (esim. languages.config.json), ja tarjoaa ne käytettäväksi muissa moduuleissa.
4. Käännösten statukset: Seuraa käännösten tilaa (esim. käännös valmis, puuttuu, epäonnistunut).
5. Tuki useille kielille: Tukee monikielisiä käännöksiä ja niiden dynaamista latausta.

Rajapinta

export type LanguageDef = {
  code: string;
  name: string;
  flag: string;
  active?: boolean;
  masterLanguage?: boolean;
  dayjsLocale?: string;
  antdLocale?: string;
};

export type TranslationResult = Record<string, string>;

export const getLanguages: () => LanguageDef[];

export const getTranslation: (key: string, lang: string) => string;

export const getMasterLanguage: () => string;

export const loadTranslations: (fileName: string) => Promise<Record<string, Record<string, string>>>;

export const getLanguageCodes: () => string[];

export const isLanguageSupported: (lang: string) => boolean;

Tarkempi selitys:

1. getLanguages(): Palauttaa listan kaikista määritellyistä kielistä (languages.config.json tai muista lähteistä ladattuna).
2. getTranslation(key: string, lang: string): Hakee käännöksen annetulta kieleltä ja palauttaa sen. Jos käännös ei ole saatavilla, palautetaan master-kielen käännös.
3. getMasterLanguage(): Palauttaa master-kielen koodin (esim. fi).
4. loadTranslations(fileName: string): Lataa käännöksiä JSON-tiedostosta (esim. projects.json).
5. getLanguageCodes(): Palauttaa kaikki tuetut kielikoodit.
6. isLanguageSupported(lang: string): Tarkistaa, onko kieli tuettu ja aktiivinen.

Tässä vaiheessa i18n-core on valmis, ja sen tarjoamia rajapintoja voi käyttää muihin moduuleihin kieliversion ja käännösten käsittelyyn. Seuraavaksi voidaan siirtyä muihin moduuleihin ja testata näiden rajapintojen integrointia muihin osiin sovellusta.