7. Namespaces, tekstfragmenten en l-files

7.1. Taal in Brocade

Brocade is taalonafhankelijk. Dit betekent dat teksten - die door de software worden aangereikt - zich aanpassen aan de taal van de gebruiker.

Er bestaat niet zoiets als een Nederlandstalige versie van Brocade: er bestaat slechts 1 versie die kan worden gebruikt in een specifieke, ondersteunde taal.

Intern werkt Brocade met codes. Deze codes worden dan gesubstitueerd met de juiste vertaling. De taalonafhankelijkheid van Brocade beperkt zich dan ook tot deze eenvoudige substitutie.

De taal die wordt gehanteerd in de dialogen wordt bepaald door de gebruiker van de software. Is deze gebruiker anoniem dan wordt de taal bepaald door de context (de opgeroepen URL).

Bij de installatie van het systeem zijn er 2 taalgebonden registry waarden van tel:

  • language-default: dit is de te gebruiken taal indien deze niet wordt gevonden in de context.

  • language-sequence: deze geeft de voorkeursvolgorden voor dialoogtalen. Indien een verwoording niet bestaat in een gegeven taal, dan kan - naargelang de toepassing - geopteerd worden om verwoordingen in een andere taal aan te bieden.

7.2. Taalcode

Elk Brocade proces werkt met een taal (al dan niet expliciet gedefinieerd). Deze code wordt meestal in de M variabele UDlg opgeborgen.

Deze code kan ook worden geïnitialiseerd met de macro: m4_language(UDlg)

In Brocade kunnen talen op 2 manieren worden gespecificeerd:

  • met behulp van ISO 639-2/B. Deze codes worden gebruikt om bijvoorbeeld de taal van een titel op te slaan in de databank.

  • dialoogtalen. Deze worden aangegeven door een hoofdletter (N, E, D, F, U). Deze codes moeten niet meteen gezien worden als geassocieerd met een geografische plaats maar kunnen ook worden gebruikt (indien gewenst) om bijvoorbeeld het onderscheid aan te geven tussen de dialogen gehanteerd in de openbare bibliotheekwereld en de academische wereld.

Speciaal is de U dialoogtaal. Deze wordt bij voorkeur gebruikt bij het opleveren van teksten in een dialoog-loze context. Een voorbeeld hiervan is bij het downloaden van catalografische beschrijvingen. Als je daar een verwoording van onderwerpscodes wil bijvoegen dan gebeurt dit het beste via de U taal.

7.3. Namespaces

Namespaces staan voor een universum van tekstcodes. Het zijn precies deze tekstcodes die kunnen worden vertaald. Elke vertaling van een tekstcode is in de context van een namespace.

Gelijke tekstcodes binnen verschillende namespaces kunnen totaal verschillende vertalingen hebben.

Er zijn 2 speciale namespaces:

De naamloze namespace

Dit is het universum van de tekstcodes die in elke Brocade installatie (van dezelfde release) gelijk is. Deze tekstcodes kunnen niet via de Brocade interface worden gedefinieerd of aangepast. Het is de taak van de Brocade ontwikkelaars om deze tekstcodes op te stellen en te onderhouden.

De default namespace

Deze is optioneel. Ze is gedefinieerd indien de registry waarde namespace-default bestaat en verschillend is van leeg. Deze namespace is manipuleerbaar via de Brocade interface en kan worden gebruikt om de verwoordingen van de naamloze namespace te overschrijven. Het onderhoud van deze namespace valt ten laste van de system administrator van de bewuste Brocade installatie. Deze namespace wordt steeds in plaats van de naamloze namespace gebruikt en enkel indien de tekstcode niet bestaat in de default namespace wordt er gekeken naar de naamloze namespace.

In Brocade is er een toepassing voorzien om namespaces aan te maken.

7.4. Tekstcodes

Tekstcodes worden steeds gedefinieerd binnen een gegeven namespace. Ze hebben diverse attributen:

  • De identifier, title en scope definiëren de tekstcode

  • De vertalingen in de diverse ondersteunde talen

  • Scopenotes in de diverse ondersteunde talen. Deze worden steeds ingevoerd in markdown formaat.

  • Niet-overschrijfbaarheid. Als deze vlag áán staat (en de bewuste vertaling is verschillend van leeg), dan kunnen vertalingen en scopes NIET worden aangepast, tenzij dan via de Brocade interface.

7.5. L-files

Brocade werkt met een speciaal bestandstype: de l-files. Bestanden van dit type (extensie .l) worden aangemaakt en onderhouden tijdens het ontwikkelproces.

Binnen de QtechNG omgeving is er een instrumentarium voorhanden om deze tekstcodes te onderhouden, niet vertaalde tekstcodes op te sporen, weg te schrijven in een spreadsheet, importeren van een spreadsheet met vertalingen.

L-files worden steeds gecodeerd in UTF-8. Op de verwoordingen van de codes wordt slechts 1 transformatie uitgevoerd: HTML character entity references worden omgevormd naar numeric entity references.

De L-files dienen in de eerste plaats om de tekstcodes te definiëren uit de naamloze namespace. De volgende paragraaf toont hoe de code warningnumbers wordt gedefinieerd:

1lgcode warningnumbers:
2    N: «Opgelet ! Er staan cijfers in de auteursnaam en dit is GEEN authority code»
3    E: «Note! There are numbers in the author name and this is NOT an authority code»
4    F: «Attention ! Le nom d'auteur contient des chiffres et il ne s'agit PAS
5        d'une notice d'autorité»

Ze kunnen echter ook worden gebruikt om namespaces en tekstcodes binnen namespaces te definiëren en te onderhouden.

Sommige namespaces zijn immers gemeenschappelijk aan alle Brocade instellingen. Ze kunnen dan ook worden gedefinieerd door ze te behandelen als een gewoon tekstcode binnen een L-file met de afspraak dat de identifier eindigt op een '.'. De QtechNG software zorgt er dan voor dat de passende namespace wordt aangemaakt. Ook van sommige tekstcodes is het wenselijk dat ze in elke Brocade installatie bestaan. Ze kunnen dan ook in L-files worden gedefinieerd met de volgende afspraken:

  • De structuur van de identifier in de L-file is: namespace.tekstcode

  • De structuur van de scope in de L-files is: namespace.tekstcode.scope

Een paar voorbeelden om een en ander te verduidelijken:

De volgende paragraaf toont hoe een namespace metaColtype wordt gedefinieerd. Let op het . op het einde van de naam.

1lgcode metaColsys.:
2    N: «Systemen voor collectiebeschrijvingen»

De volgende paragraaf toont hoe een tekstfragment wordt gezet vanuit een L-file:

1lgcode metaColsys.docstore:
2    N: «Docstore omgeving»

Scope notes bij een tekstfragment kunnen eveneens worden getoond binnen een L-file:

1lgcode metaColsys.docstore.scope:
2    N: «In deze docstore omgeving worden allerlei vaste documenten (of URLs) geplaatst
3        die betrekking hebben op dit collectiesysteem.
4
5        Voorbeelden zijn documenten die de toegang beschrijven tot de collectie»

QtechNG zorgt ervoor dat tekstcodes (en hun namespaces) automatisch worden aangemaakt. QtechNG zal ook de veranderingen aan de vertalingen doorvoeren, tenminste tot zolang de niet-overschrijfbaarheid vlag van de bewuste tekstcode af staat.

Merk nog op dat op deze wijze ook de default namespace kan worden onderhouden.

Laten we even stilstaan bij het verschil tussen namespaces en l-files.

Of een verwoording thuishoort in een namespace of in een l-file, wordt bepaald door één overweging: hoort de verwoording bij elke Brocade installatie, dan wordt de verwoording het beste in een l-file geplaatst.

Is de verwoording specifiek voor een Brocade installatie, dan gebeurt de verwoording in een namespace.

Je zou ook kunnen stellen: het onderhoud van de l-files is de verantwoordelijkheid van de ontwikkelaars, het onderhoud van de namespaces (de vertaling van de tekstfragmenten) ligt bij de lokale verantwoordelijken. l-files worden ook door het Brocade update proces overschreven.

7.6. Tekstcode representaties

Tekstcodes kunnen op 3 manieren worden gerepresenteerd (herinner dat een vertaling steeds gebeurd binnen een namespace):

  • .tekstcode: beginnend met een punt wordt de tekstcode steeds gezocht in 2 fasen:

    1. binnen de default namespace. Indien de tekstcode wordt gevonden, dan stopt het proces.

    2. binnen de naamloze namespace

  • namespace.tekstcode: de tekstcode wordt steeds gezocht binnen de gegeven namespace

  • namespace..tekstcode: Opnieuw zijn er 2 fasen:

    1. wordt namespace.tekstcode gevonden, dan worden deze vertalingen gebruikt en het proces stopt.

    2. de vertalingen van .tekstcode wordt gebruikt.

Merk nog op dat er niet werd geopteerd voor een LOI. De representaties worden vooral gebruikt binnen templates en de : delimiters en vaste prefix zouden storend werken binnen de template syntax.

7.7. Macros in verband met tekstcodes

De eenvoudigste en tegelijkertijd ook de belangrijkste macro is wel:

macro sayText($say, $id, $ns=".", $lg="", $enc="", $default" "», $cache=1):
    '''
    $synopsis: Geeft de vertaling van de tekstcode.
               Eventueel kan deze worden geëncodeerd!
    $say: Vertaling van een tekstcode
    $id: tekstcode
         bevat deze een punt dan:
         - eindigt op een ".": tekstcode wordt gezien als een namespace
                               en de verwoording van deze wordt geproduceerd
         - begint met een ".": lgcode
         - middenin 1 ".": voor het punt is de namespace, na het punt het tekstid
         - middenin "..": eerst wordt de verwoording opgezocht in de namespace,
                          las dit faalt als lgcode
    $ns: Namespace
                Is de namespace "", dan wordt gekeken of er een lgcode bestaat met deze id
    $lg: Taal  (N, E, D, U, F)
         Is de taal "", dan wordt de language macro aangewend
         Is de taal "@", wordt de generieke verwoording terug gegeven
         Bevat de taal een "*", dan:
         (1) de "*" wordt weggehaald uit de taal
         (2) de taal gaat door de language macro
         (3) dit resultaat wordt aangevuld met de registry waarde language-sequence
         (4) alle talen uit deze string worden in volgorde geprobeerd
    $enc: De waarden worden geencodeerd.
          Indien leeg dan is er geen encodering. Waarden kunnen zijn: url | js | py | xml | utf8 | hex |HEX
    $default: default waarde
    $cache: 0 | 1 (=haal uit cache)
    $example: m4_sayText(RDsay, "title", "thing")
    '''
    «s UDnspace=$g(UDnspace) s $say=$$%Say^utxtwtxt($id,$ns,$lg,$enc,$default,$cache)»

De optionele elementen vragen nog enige toelichting:

lg: Is deze waarde leeg, dan wordt m4_language(UDlg) gebruikt. Bevat deze waarde een *, dan worden de volgende stappen doorlopen:

  1. de "*" wordt weggehaald uit de taal

  2. de taal gaat door de language macro

  3. dit resultaat wordt aangevuld met de registry waarde language-sequence

  4. alle talen uit deze string worden in volgorde geprobeerd. Dit proces stopt wanneer een vertaling wordt gevonden.

enc: De vertaling wordt gecodeerd volgens deze waarde. Geldige waarden zijn: url | js | py | xml | utf8 | hex | HEX

default: Wordt enkel gebruikt indien er geen vertaling wordt gevonden. Er zijn dan 2 opties:

  1. deze waarde is een spatie: de vertaling wordt dan een passend fout bericht

  2. deze waarde wordt de vertaling.

De verwoordingen van een tekstfragment worden ook in een cache ondergebracht: het werk om de passende verwoording op te zoeken is immers steeds dezelfde.