Internationalisering met de Angular standaard en Localazy

Internationalisering is een belangrijke stap om een applicatie toegankelijk te maken voor een wereldwijd publiek. Maar vertalingen zijn berucht moeilijk te onderhouden en makkelijk verkeerd te doen. De ingebouwde oplossing van Angular, Angular Localize, slaat ze op in XLIFF-bestanden. Deze zijn XML-gebaseerd, zien er op het eerste gezicht rommelig uit en zijn niet bepaald prettig te lezen of te onderhouden in de IDE. Gecombineerd met het ontbreken van ondersteuning voor runtime-vertalingen is het geen verrassing dat veel ontwikkelaars alternatieven gebruiken zoals ngx-translate of Transloco. 

Runtime-vertalingen kunnen handig zijn, maar in de meeste applicaties kiest een gebruiker zijn taal bij het opstarten en verandert die zelden meer. Ook al lijken alternatieven vaak eenvoudiger om in te stellen, die eerste indruk kan misleidend zijn. Door van de standaard af te wijken loop je krachtige functies mis die Angular’s ingebouwde aanpak juist wél biedt: functies die ontworpen zijn voor betrouwbaarheid, consistentie en naadloze integratie met professionele vertaalworkflows. Die rommelig ogende XLIFF-bestanden maken deel uit van een gevestigde industriestandaard, en vasthouden daaraan kan op de lange termijn veel tijd en frustratie besparen.

Waarom Angular Localize? 

Allereerst is Angular een opinionated framework met een reden. Een van zijn grootste sterke punten ten opzichte van andere libraries en frameworks is dat het een duidelijke, consistente manier biedt om dingen te doen. Een nieuwe ontwikkelaar weet meteen hoe hij routes moet beveiligen, HTTP-verzoeken moet onderscheppen of het single responsibility principle moet volgen. Localisatie zou niet anders moeten zijn. Door de standaard van Angular te volgen blijft je project consistent en voorspelbaar. 

Ten tweede is het het formaat dat professionele vertalers verkiezen. XLIFF-bestanden ogen voor ontwikkelaars misschien rommelig, maar tools zoals Lokalise, Transifex of Localazy zijn gebouwd om ze te lezen en de vertalingen in een overzichtelijke, gebruiksvriendelijke interface weer te geven. Deze tools behouden ook context, waardoor vertalers eenvoudiger nauwkeurige vertalingen kunnen leveren zonder eindeloze heen-en-weer communicatie. 

Ten derde zijn compile-time vertalingen meestal veel efficiënter dan runtime. Terwijl runtime-oplossingen vertaalbestanden kunnen lazy-loaden, voegen ze toch overhead toe tijdens de uitvoering van de app. Bij compile-time vertalingen downloadt de gebruiker alleen de taalversie die nodig is, wat sneller en lichter is. En in de meeste gevallen hoeft een gebruiker de taal niet dynamisch te wisselen. Ze kiezen die aan het begin en houden die de hele sessie. Bovendien fungeert je brontaal automatisch als fallback. Ontbrekende vertalingen tonen dan gewoon leesbare tekst in plaats van cryptische keys. 

Ten vierde gaat localisatie verder dan alleen vertalen. Arabisch en Hebreeuws worden van rechts naar links gelezen. Duitsers zetten hun valutateken achter het bedrag. Frans gebruikt decimale komma’s in plaats van punten. En er zijn nog talloze andere voorbeelden. Angular Localize regelt deze culturele en regionale variaties als onderdeel van de frameworkimplementatie, waardoor localisatie meer is dan alleen woorden vervangen. 

En tot slot: de leesbaarheid tijdens ontwikkeling. Omdat compile-time vertalingen in Angular Localize de originele tekst inline in je templates laten staan, is het veel eenvoudiger om de bedoeling van een component of de context van een pagina te begrijpen tijdens het coderen. Runtime-oplossingen zoals Transloco of ngx-translate vertrouwen daarentegen op keys in JSON-bestanden. Keys kunnen beschrijvend zijn, maar halen het zelden bij de duidelijkheid van de originele tekst op de plek waar die gebruikt wordt. 

Waarom ontwikkelaars alternatieven verkiezen 

Ondanks alle redenen om Angular Localize te gebruiken, klinkt het allemaal niet zo eenvoudig als het lijkt. Er is een reden dat veel ontwikkelaars liever alternatieve tools gebruiken. De meeste werken “gewoon” na een enkele build — makkelijk te deployen, makkelijk te hosten. Je kunt de bestanden neerzetten op een statische host en alles draait meteen. Het onderhouden van een set JSON-bestanden voelt ook eenvoudiger: één regel, één vertaling. 

Angular Localize werkt anders. Het bouwt aparte versies van de applicatie voor elke taal en slaat vertalingen op in lange, XML-gebaseerde XLIFF-bestanden. Dat betekent dat je een manier moet hebben om de juiste taalversie dynamisch te serveren en een proces moet inrichten om vertalingen efficiënt te beheren. Op het eerste gezicht lijkt dat extra werk vergeleken met JSON-oplossingen. 

Soms is dat extra werk het gewoon niet waard. Voor een kleine applicatie met slechts twee talen kan een alternatieve library praktischer zijn. Maar wanneer een applicatie moet opschalen, meerdere talen moet ondersteunen of aan enterprisestandaarden moet voldoen, loont het volgen van de Angular-standaard. En het goede nieuws is: met de juiste tooling verdwijnt veel van die vermeende complexiteit volledig. 

In de volgende sectie kijken we hoe Angular Localize in combinatie met Localazy het proces veel eenvoudiger maakt dan de meeste ontwikkelaars verwachten. 

Aan de slag met Angular Localize 

De eerste stap is het installeren van het pakket. Omdat Angular Localize onderdeel is van het Angular-framework, is installatie eenvoudig: 

ng add @angular/localize 

Dit commando voegt de vereiste polyfills toe, configureert de extract-i18n-sectie in je angular.json, en stelt localize-types in bij je compileropties zodat je i18n en $localize kunt gebruiken zonder imports. 

Daarna kun je tekst markeren voor vertaling. Gebruik i18n in templates en $localize in TypeScript: 

<h1 i18n> 
  Welcome to {{ title() }}! 
</h1> 

title = signal($localize`medium`); 

Om vertalers meer context te geven kun je een beschrijving en unieke identifier toevoegen. Dit is optioneel, maar sterk aanbevolen. 

<h1 i18n="This is a friendly welcome message@@app--welcome-message"> 
  Welcome to {{ title() }}! 
</h1> 

title = signal( 
  $localize`:This is the title of your application@@app--title:medium` 
); 

Alles na @@ is de unieke identifier. Met $localize komen beschrijving en identifier tussen dubbele punten. Een goede conventie is component-naam — beschrijving voor duidelijkheid. 

Als je teksten gemarkeerd zijn, kun je ze extraheren: 

ng extract-i18n 

Dit genereert een messages.xlf-bestand in de projectroot. Je kunt de uitvoerlocatie aanpassen in angular.json, bijvoorbeeld naar src/locales: 

{ 
  "projects": { 
    "{your-project-name}": { 
      "architect": { 
        "extract-i18n": { 
          "builder": "@angular-devkit/build-angular:extract-i18n", 
          "options": { 
            "outputPath": "src/locales" 
          } 
        } 
      } 
    } 
  } 
} 

Vervolgens declareer je de talen die je wilt ondersteunen. Voeg een i18n-sectie toe aan angular.json om de brontaal (de taal in je code) en de locaties van de andere locale-bestanden te definiëren: 

{ 
  "projects": { 
    "{your-project-name}": { 
      "i18n": { 
        "sourceLocale": "en", 
        "locales": { 
          "nl": "src/locales/messages.nl.xlf" 
        } 
      } 
    } 
  } 
} 

Pas ten slotte de buildopties aan om in productie alle talen te includeren en in development slechts één (voor snellere ng serve): 

{ 
  "projects": { 
    "{your-project-name}": { 
      "architect": { 
        "build": { 
          "options": { 
            "localize": ["en", "nl"] 
          }, 
          "configurations": { 
            "development": { 
              "localize": ["en"] 
            } 
          } 
        } 
      } 
    } 
  } 
} 

Na deze stappen kun je messages.xlf kopiëren, hernoemen naar messages.nl.xlf en in dezelfde map plaatsen. Je kunt je applicatie nu bouwen, maar er zijn nog geen vertalingen toegevoegd. Het handmatig onderhouden van meerdere talen kan tijdrovend zijn, dus het helpt om gratis open-source editors te gebruiken met Translation Memory, zoals POEdit. Op dit punt — gefeliciteerd — heb je Angular Localize opgezet volgens de standaard. 

En dit is pas het begin. Met de juiste tools kan het proces nog schoner en beter schaalbaar worden. Professionele platforms zoals Lokalise of Localazy tillen vertaalbeheer naar een hoger niveau, wat we in de volgende sectie bekijken. 

Je leven makkelijker maken met Localazy

Bezoek https://localazy.com en meld je aan voor een gratis proefperiode. Maak een project aan en selecteer je brontaal. 

In het menu aan de rechterkant vind je onder Project settings → Access Keys je schrijf- en leessleutels — bewaar deze altijd veilig. 

Installeer in je project de Localazy CLI: 

npm i -D @localazy/cli 

Maak twee nieuwe bestanden in de root van je project: 

localazy.json 

{ 
  "upload": { 
    "type": "xliff", 
    "files": "src/locales/messages.xlf" 
  }, 
  "download": { 
    "files": "src/locales/${fileWithoutExt}.${languageCode}.xlf" 
  } 
} 

localazy.keys.json 

{ 
  "writeKey": "{secret-write-key}", 
  "readKey": "{secret-read-key}" 
} 

Zorg dat je localazy.keys.json toevoegt aan je .gitignore. Voor eenvoud gebruik ik hier het .keys-bestand, maar in productie kun je beter de sleutels via flags en veilige omgevingsvariabelen in je CI-pipeline doorgeven. 

Upload vervolgens alle vertalingen naar Localazy: 

npx localazy upload 

In het Localazy-portaal kun je talen toevoegen via Translations → Add Languages. Je kunt machinevertalingen gebruiken of handmatig vertalen. Context die je in de code hebt meegegeven wordt getoond, en je kunt zelfs screenshots uploaden om vertalers extra context te bieden. 

Om vertalingen te updaten in je app: 

npx localazy download 

De nieuwste bestanden worden gedownload en opgenomen in je broncode. Voor nog meer automatisering integreer je extract-, upload- en downloadstappen direct in je CI-pipeline. Met deze aanpak kunnen wij meer dan 20 talen toegevoegd en onderhouden in minder dan een uur. 

Meerdere talen serveren 

Met je vertalingen op orde is de laatste stap ervoor zorgen dat gebruikers de juiste taalversie van je applicatie ontvangen. Omdat Angular Localize aparte builds maakt voor elke taal, moet je server zo worden ingericht dat die de juiste bestanden serveert op basis van de taal van de gebruiker of het gekozen URL-pad. 

Het Angular-team biedt hiervoor een uitstekende gids, met kant-en-klare voorbeelden voor Nginx en Apache. Dit dekt alles van taalspecifieke subfolders tot correcte routing zodat deep links in alle talen blijven werken. 

Afronding

Een Angular-applicatie lokaliseren hoeft niet te betekenen dat je weer een nieuwe library toevoegt. Angular Localize, met zijn XLIFF-gebaseerde workflow, biedt een consistente, efficiënte en vertaler-vriendelijke aanpak die al in het framework zit. JSON-oplossingen met runtime lijken eenvoudiger, maar leveren vaak in op prestaties, schaalbaarheid en integratie met professionele vertaaltools. 

Door de standaard te volgen houd je je project schoner en voorspelbaarder, terwijl je profiteert van een oplossing die ontworpen is om het volledige spectrum van localisatie te ondersteunen: van taalwissel tot culturele formatting. En met de juiste tooling gaat het beheren van vertalingen sneller en makkelijker dan veel ontwikkelaars verwachten. 

Uiteindelijk draait Angular Localize niet alleen om het vertalen van strings. Het gaat om het leveren van een wereldwijd toegankelijke applicatie, zonder onnodige complexiteit. 

Hulp nodig?

Internationalisering is waarschijnlijk niet het eerste waar je aan denkt bij het bouwen van een applicatie. Toch kan het een flinke meerwaarde zijn. Het gaat verder dan alleen een knopje waarmee je een andere taal kiest. Denk er bijvoorbeeld aan dat je API altijd foutmeldingen teruggeeft in de voorkeurstaal van de gebruiker. Of dat iemand in de instellingen zelf zijn voorkeurstaal kan kiezen en dit in de hele applicatie consequent wordt doorgevoerd. Ook rapportages, notificaties en exports kunnen direct in de juiste taal aangeboden worden. 

Dit soort details maken het verschil tussen “het werkt” en “het voelt echt goed aan” voor eindgebruikers, zeker in internationale omgevingen waar meerdere talen door elkaar gebruikt worden. 

Als Localazy-partner kan Delta-N helpen om dit proces gestructureerd en schaalbaar op te zetten. Of dat nu voor Angular, React, C# of een andere technologie is, wij zorgen dat internationalisatie aansluit op jullie ontwikkelproces en CI/CD-pijplijn. 

Vrijblijvend contact opnemen mag altijd. Plan hier direct een online afspraak met een van onze accountmanagers: plan een afspraak. 

Deze blog is geschreven op basis de persoonlijke blog van één van onze domein experts.