Bouw de relevante doelen, controleer elke tekenreekscatalogus voor alle ondersteunde talen en test vervolgens de berichtvarianten in de draaiende app om elke lokalisatiesleutel in een Mac-app te controleren. Volledigheid van de catalogus en correcte weergave tijdens runtime vereisen afzonderlijke controles.

Deze workflow is bedoeld voor een ontwikkelaar die met Xcode een Mac-desktopapp onderhoudt. Het concrete doel is een traceerbaar overzicht op te stellen van ontbrekende berichten, onvoltooide vertalingen, onjuiste argumenten en weergaveproblemen. De voorbeelden gebruiken fictieve labels en aantallen; ze beschrijven een controlemethode die je op je eigen project kunt toepassen.

Bepaal wanneer een bericht als volledig geldt

Begin met een klein controlewerkblad. Noteer het appdoel, de resourcebundel, de tekenreekstabel, de sleutel, de ondersteunde lokalisatie, de vereiste varianten, de vertaalstatus en het runtime-resultaat. Behandel elke combinatie van bundel, tabel en sleutel als een afzonderlijke berichtidentiteit, zodat identieke sleuteltekst in verschillende resources geen weglating verhult.

Apple documenteert dat API’s voor lokaliseerbare tekst een tabel en bundel kunnen opgeven, en dat resources buiten de hoofdbundel de juiste bundel nodig hebben om ze te kunnen opzoeken. Als je alleen het standaardbestand Localizable.xcstrings controleert, kun je dus berichten elders in de app missen. Zie De tekst van je app voorbereiden op vertaling.

Lees de ondersteunde lokalisaties van het project af in de projecteditor: selecteer het project onder Project, open Info en bekijk Localizations. Controleer ook welke resources aan die lokalisaties deelnemen. In Ondersteuning toevoegen voor talen en regio’s legt Apple deze projectinstellingen en resourceselecties uit.

Je kunt in het werkblad fictieve aliassen gebruiken, zoals Lokalisatie A, Lokalisatie B en Lokalisatie C. Houd in je werknotities bij welke daadwerkelijke lokalisatie-identificaties van het project bij deze aliassen horen. Deze aliassen zijn labels voor het werkblad en geen waarden die je in Xcode moet invoeren.

Gebruik voor de controle de volgende criteria om te bepalen of iets volledig is. Dit is een voorgestelde controlemethode, geen door Apple gedefinieerde status.

Controle Vast te leggen bewijs
Inventaris Het bericht heeft een geïdentificeerd doel, een bundel, een tabel en een sleutel.
Detectie Het bericht is uit code geëxtraheerd of wordt bewust handmatig bijgehouden.
Dekking Elke vereiste lokalisatie heeft de benodigde berichtvarianten.
Argumenten Elk argument behoudt de bedoelde betekenis en een compatibel type.
Runtime Het juiste bericht en de juiste waarden verschijnen in de relevante Mac-interface.
Afhandeling Elke bevinding is opgelost, bewust met een reden uitgesloten of nog open.

Stel eerst de catalogusinventaris samen en controleer daarna de vertalingen

Open de bestaande tekenreekscatalogi van het project. Als een doel geen catalogus heeft, is de door Apple gedocumenteerde aanmaakroute File > New > File from Template; selecteer vervolgens String Catalog. De standaardnaam is Localizable; gebruik de tabelnaam die je code verwacht. Kies Product > Build om de catalogus te vullen en bij te werken. Zie Tekst lokaliseren en variëren met een tekenreekscatalogus.

Bouw elk relevant Mac-schema in plaats van één geslaagde build als de volledige inventaris te beschouwen. Apple legt uit dat extractie tekenreeksen opspoort voor het huidige schema en platform. Een bericht dat in één build ontbreekt, verdient nader onderzoek voordat je concludeert dat het ongebruikt is. Deze beperking wordt beschreven in Tekenreekscatalogi opsporen.

Controleer de buildinstelling Use Compiler to Extract Swift Strings. Apple vereist expliciet dat deze instelling aanstaat om alle lokaliseerbare Swift-tekst in lokalisatie-exporten op te nemen. Als je een uitwisselkopie nodig hebt voor vertaalwerk, selecteer je het project en kies je Product > Export Localizations; kies daarna de vereiste lokalisaties. Het geëxporteerde .xcloc-pakket is een Xcode Localization Catalog en verschilt van een afzonderlijke .xcstrings-tekenreekstabel. Zie Lokalisaties exporteren.

Loop vervolgens de gebruikelijke onderdelen van de desktopapp na: het hoofdvenster, menu’s, de werkbalk, instellingen, panelen, lege toestanden en labels die afhankelijk zijn van aantallen. Zoek voor elk app-eigen bericht dat je tegenkomt de bijbehorende vermelding in het werkblad. Deze omgekeerde controle, van zichtbare interface naar inventaris, helpt tekst te vinden die nooit in een catalogus is terechtgekomen.

Ga er niet van uit dat extractie elke willekeurige tekenreeksexpressie opspoort. Apple beschrijft extractie via API’s voor lokaliseerbare tekst. Ontbreekt een verwacht bericht, controleer dan hoe de code het aanmaakt en doorgeeft voordat je handmatig een tweede vermelding toevoegt. Zie De tekst van je app voorbereiden op vertaling.

Houd extractie, opzoeken en opmaak tijdens runtime uit elkaar

Deze bewerkingen beantwoorden verschillende vragen. Bij extractie gaat het erom of Xcode tijdens de ontwikkeling een bericht kan opsporen. Bij opzoeken gaat het erom welke gelokaliseerde resource de draaiende app opvraagt. Bij opmaak tijdens runtime wordt variabele inhoud ingevuld in het geselecteerde bericht.

Bij SwiftUI zijn de argumenttypen van belang. Een letterlijke waarde zoals Text("Open collection") wordt opgezocht in de lokalisatie. Als je een gewone String-variabele doorgeeft aan de bijbehorende initializer, wordt die variabele doorgaans zonder lokalisatie weergegeven. Apple documenteert dit onderscheid in LocalizedStringKey.

Als je expliciet een LocalizedStringKey aanmaakt op basis van een variabele, wordt het bericht opgezocht. Dat betekent echter niet dat build-time-extractie alle mogelijke variabele waarden heeft gevonden. Vergelijk bij dynamisch gekozen sleutels de volledige set toegestane sleutels met de catalogus. Onderzoek elke waarde zonder overeenkomst in plaats van te vertrouwen op de waarde die toevallig tijdens een test is verschenen.

Interpolatie speelt ook een rol op berichtniveau. SwiftUI kan een gelokaliseerd bericht met een formaatspecificatie opzoeken en de geïnterpoleerde waarde invoegen voordat het bericht wordt weergegeven. Apple beveelt interpolatie aan om lokaliseerbare tekst samen te stellen in de documentatie bij Text.

Neem als voorbeeld een bericht dat het aantal items meldt. De catalogus bevat de lokaliseerbare berichtstructuur en varianten; het veranderende aantal hoort bij het gedrag tijdens runtime. Voor tests met aantallen 1 en 24 zijn niet twee afzonderlijk bijgehouden sleutels nodig, alleen omdat het getal verandert.

Een label dat er aannemelijk uitziet, is zwak bewijs dat het opzoeken is geslaagd. Apple geeft aan dat SwiftUI de sleutel zelf kan weergeven als de gelokaliseerde waarde niet wordt gevonden. Als een sleutel leesbare brontekst is, kan een probleem met opzoeken eruitzien als een gewoon label. Controleer naast het weergegeven resultaat ook de geselecteerde lokalisatie en de catalogusvermelding. Zie Weergaven voorbereiden op lokalisatie.

Controleer elke taal en elke vereiste variant

Werk één tabel en één lokalisatie tegelijk door. Controleer voor elk bericht de vertaalstatus, de tekst, de argumenten en de uitgebreide varianten. Laat onvoltooide rijen open, ook als de omringende berichten klaar zijn.

De catalogusworkflow van Apple onderscheidt New, Needs Review, vertaalde vermeldingen en Stale tekenreeksen. Een verouderde vermelding is niet langer in de code aangetroffen; handmatig beheerde vermeldingen worden tijdens synchronisatie niet automatisch bijgewerkt of verwijderd. Bevestig dat een verouderde sleutel overbodig is voordat je de vertalingen ervan verwijdert. Zie Tekenreekscatalogi opsporen.

Als een bericht afhankelijk is van een aantal, klik je met Control ingedrukt op de geïnterpoleerde sleutel en kies je Vary by Plural. Controleer alle vormen die Xcode voor elke lokalisatie opgeeft. De vereiste vormen kunnen verschillen; hetzelfde aantal rijen als in de bronlokalisatie is dus geen voldoende controle. Als de catalogus apparaatvarianten bevat, controleer dan zowel de Mac-specifieke waarde als de algemene waarde. Apple documenteert beide opties in Tekst lokaliseren en variëren met een tekenreekscatalogus.

Controleer argumenten zowel op betekenis als op uiterlijk. Bepaal voor een fictief bericht over items in groepen welk argument het aantal items voorstelt en welk argument het aantal groepen. Een vertaling kan de volgorde veranderen, maar moet die betekenissen behouden. Apples uitleg over catalogussessies behandelt argumentposities, typespecificaties en vervangingen voor meervoudsvormen in Tekenreekscatalogi opsporen.

Voeg context toe als een kort label dubbelzinnig is. Een opmerking bij Open kan bijvoorbeeld aangeven dat het de actie op een rij in een verzameling is. SwiftUI’s parameter comment geeft die context door aan de lokalisatie-uitvoer; Apple beschrijft dit in Weergaven voorbereiden op lokalisatie.

Gebruik een dekkingsmatrix die onvoltooid werk zichtbaar maakt

Een enkel percentage is nuttig om de voortgang van de catalogus bij te houden, maar voor de controle zijn afzonderlijke kolommen nodig voor dekking en gedrag. Het volgende uitgewerkte voorbeeld laat zien waarom. De aantallen zijn fictief en staan voor paren van bericht en lokalisatie, niet voor metingen van een app.

Stel dat de inventaris 48 vereiste berichten en drie ondersteunde lokalisaties bevat. Dat levert 144 vereiste paren op: 48 vermenigvuldigd met 3. Elk paar kan extra meervouds- of apparaatvarianten bevatten die afzonderlijk moeten worden gecontroleerd.

Lokalisatie Vereiste paren Cataloguscontroles voltooid Runtimecontroles voltooid
Lokalisatie A 48 48 48
Lokalisatie B 48 46 44
Lokalisatie C 48 48 45
Totaal 144 142 137

Er moeten hier nog twee paren in de catalogus worden afgehandeld en voor zeven paren moeten de runtimecontroles nog worden voltooid. Die groepen kunnen elkaar overlappen, dus ze optellen geeft geen betrouwbaar aantal unieke onvoltooide berichten. Houd beide bevindingen gekoppeld aan de bijbehorende rijen.

Noteer voor elke onvoltooide rij een concrete volgende actie: een ontbrekend bronbericht zoeken, een meervoudsvariant voltooien, een argument controleren, de bundelselectie onderzoeken of de interface opnieuw bekijken op een smallere breedte. Zo wordt de matrix een reparatiewachtrij in plaats van een decoratief voortgangsrapport.

Voer de Mac-app uit in elke ondersteunde lokalisatie

Gebruik de schemainstellingen van Xcode om herhaalbare controles op appniveau uit te voeren. Kies Product > Scheme > Edit Scheme, selecteer Run, open Options en kies App Language en App Region. Sluit het venster, selecteer de Mac-uitvoerbestemming en voer de app uit. Herhaal dit voor de combinaties die je in je controle hebt opgenomen. Apple documenteert deze stappen in Lokalisaties testen wanneer je app wordt uitgevoerd.

Volg bij elke uitvoering dezelfde route door de interface. Test elk bericht met relevante toestanden: een lege verzameling, één item, meerdere items en langere fictieve labels. Kies voor berichten met meervoudsvormen aanvullende waarden die nodig zijn om de takken in die lokalisatie te testen; een kleine vaste set aantallen biedt geen volledige dekking van alle takken.

Controleer volledige zinnen, ingevulde waarden, regelafbreking, afkapping en de breedte van menu’s en bedieningselementen. Varieer bij een bericht met twee aantallen beide aantallen onafhankelijk van elkaar. Als je bijvoorbeeld het aantal items verandert terwijl het aantal groepen gelijk blijft, kan dat fouten in de koppeling van argumenten aan het licht brengen.

Met SwiftUI-previews kun je de reparatiecyclus verkorten. Apple ondersteunt het instellen van de omgevingswaarde locale van de preview en het maken van meerdere previews met verschillende lokalisaties nadat je die hebt toegevoegd of geïmporteerd. Gebruik ze om een lastig onderdeel opnieuw te bekijken en controleer daarna het daadwerkelijke apppad. Zie Lokalisaties bekijken in previews.

Sluit de controle pas af als voor elk vereist paar van bericht en lokalisatie een gedocumenteerde afhandeling is vastgelegd en de benodigde vertakkingen zijn gecontroleerd. Bewaar de inventaris, testroute en onopgeloste bevindingen bij elkaar. Zo is de volgende controle direct uitvoerbaar: van een gewijzigd bericht zijn de locatie, verwachte argumenten, vereiste varianten en een herhaalbare manier om de weergave te controleren bekend.

Bronnen