GraphQL-design for oversatte tekster

For felter som finnes på flere språk er målbildet at vi eksponerer to varianter ved siden av hverandre:

• navn: OversattTekst — verdien på det språket klienten har bedt om via Accept-Language-headeren, med språkkoden som faktisk ble brukt. Ikke støttet i Graphitron i dag — se advarselen under.
• navnAlleSprak: OversatteTekster — alle tilgjengelige språkvarianter samtidig. Dette er det som er tilgjengelig per nå.

Når headerstøtten er på plass i Graphitron vil applikasjoner typisk bruke navn og la APIet håndtere språkvalg og fallback, mens integrasjoner som henter data for videre bearbeiding vil bruke navnAlleSprak. Inntil da skal nye felter eksponeres som navnAlleSprak alene.

Schema-definisjon

"""
En tekst på ett språk, med språkkoden som faktisk ble levert.
Språkkoden følger med slik at klienten kan se om fallback ble brukt.
"""
type OversattTekst @record(name: "no.sikt.fs.jooq.generated.records.embedded.OversattTekst") {
  sprakkode: String
  verdi: String
}

"""
Representerer en tekst som kan være tilgjengelig på flere språk som er støttet.
"""
type OversatteTekster {
  """Engelsk"""
  en: String
  """Norsk bokmål"""
  nb: String
  """Nynorsk"""
  nn: String
  """Samisk"""
  se: String
}

"""
Input-type for å opprette eller oppdatere oversatte tekster.
Har samme struktur som OversatteTekster-typen.
"""
input OversatteTeksterInput {
  """Engelsk"""
  en: String
  """Norsk bokmål"""
  nb: String
  """Nynorsk"""
  nn: String
  """Samisk"""
  se: String
}

Språkvalg via Accept-Language-header

Ikke implementer dette mønsteret manuelt ennå

Accept-Language-mønsteret beskrevet under er ikke støttet i Graphitron i dag. Direktivet @i18nField finnes ikke ennå, og det er ikke maskineri på plass for å lese headeren og velge riktig kolonne/fallback.

Ikke håndkod denne oppførselen i den enkelte tjenesten. Be heller om at Graphitron-saken prioriteres, og bruk eventuelt navnAlleSprak: OversatteTekster inntil videre.

For uthenting bruker vi HTTP-headeren Accept-Language til å angi ønsket språk. Klienten sender for eksempel Accept-Language: en, og APIet returnerer da navn på engelsk. Dersom verdien ikke finnes på det forespurte språket, faller APIet tilbake til et default-språk (typisk bokmål). Fordi OversattTekst inneholder både sprakkode og verdi, kan klienten alltid se hvilket språk som faktisk ble levert og dermed oppdage at fallback er brukt.

Det er API-klientens ansvar å bestemme verdien av Accept-Language — om den følger av nettleserinnstillingene til brukeren eller settes på annet vis er ikke relevant for APIet. Vi bør vurdere hvorvidt vi skal støtte flere språk og prioritering av disse i headeren, jf. MDN: Accept-Language.

Designet gjør at frontend bare forholder seg til én strengverdi per felt og slipper å hente alle språkvarianter for så å plukke ut den riktige. Det reduserer overfetching og fjerner overhead i klientene.

Graphitron-støtte

For å holde på schema-first-implementeringen vi bruker i dag, er planen å innføre et nytt direktiv i Graphitron som lar oss angi hvilke kolonner som inneholder hvilke språkvarianter for et felt, samt hvilket språk som skal være default ved fallback, eksempelvis slik:

type Studieprogram @table {
  """Studieprogramnavn på det språket Accept-Language angir"""
  navn: OversattTekst @i18nField(
    mapping: {
      nb: "STUDIEPROGNAVN"
      nn: "STUDIEPROGNAVN_NYNORSK"
      en: "STUDIEPROGNAVN_ENGELSK"
      se: "STUDIEPROGNAVN_SAMISK"
    }
    defaultLanguage: NB
  )

  """Studieprogramnavn på alle støttede språk"""
  navnAlleSprak: OversatteTekster
}

En POC for headerbasert språkvalg ligger i merge request fs-plattform!3672, og bakgrunn og kodeeksempler er beskrevet i denne Confluence-siden.

Flerspråklig søk og filtrering

Når en query filtrerer på et felt som har flere språkvarianter, søker vi som standard i alle tilgjengelige språkvarianter for kolonnen. I tillegg legger vi til et sokSprak-felt på filteret slik at klienten kan begrense søket til spesifikke språk:

# Matcher mot alle språkvarianter når sokSprak utelates / er null
# Begrenser til bokmål og nynorsk når sokSprak er satt
filter: {
  studieprogramnavnContains: "informatikk"
  sokSprak: [NB, NN]
}

Å filtrere på alle språk by default speiler oppførselen man finner i flere etablerte prosjekter, og gir mest forutsigbare treff for klienter som ikke selv vet hvilket språk teksten er lagret på.