Een nuttige opmerking voor vertalers legt uit wat een label betekent, waar het verschijnt en wat er gebeurt wanneer iemand het gebruikt. Deze gids laat zien hoe je zulke opmerkingen schrijft en toevoegt in Xcode voor een eenvoudige Mac-app om vormen te bekijken, met synthetische Engelse labels.

Wat moet een opmerking voor vertalers uitleggen?

Begin met de keuze die een vertaler moet maken. Bij een kort label zoals Round is de grammaticale rol en de bedoelde betekenis niet duidelijk. Een opmerking kan aangeven dat het een bijvoeglijk naamwoord is dat een categorie vormen beschrijft, en uitleggen dat het boven een groep voorbeelden verschijnt. Apple raadt opmerkingen aan die verduidelijken waar en hoe een tekenreeks in de interface wordt gebruikt. Ontdek String Catalogs

Voor iemand die de labels van een Mac-app voorbereidt op vertaling, is de concrete taak om van elke dubbelzinnige tekenreeks een beknopte, op zichzelf staande uitleg te maken. De vertaler moet het doel ervan kunnen begrijpen zonder de broncode te hoeven doorzoeken.

Gebruik dit hulpmiddel met vier onderdelen. Het is een redactionele methode gebaseerd op Apples richtlijnen, geen verplicht Apple-formaat voor opmerkingen:

Onderdeel Vraag om te beantwoorden Voorbeeld
Betekenis Waar verwijst de brontekst naar? Round beschrijft vormen met gebogen omtrekken.
Rol in de gebruikersinterface Om wat voor soort interfacetekst gaat het? Een categoriekop boven voorbeelden van vormen.
Gedrag of locatie Wat gebeurt er, of wat staat eromheen? Expand toont details onder het voorbeeld.
Variabele inhoud Wat kan elke ingevoegde waarde bevatten? De eerste waarde is een vormnaam; de tweede een collectienaam.

Neem alleen onderdelen op die van invloed zijn op de interpretatie. Een statische kop hoeft geen uitleg over een actie. Bij een knop is het nuttig om duidelijk te beschrijven wat er gebeurt als je erop klikt. Bij een bericht met twee ingevoegde namen moet de relatie tussen die namen worden uitgelegd.

Apple adviseert specifiek om het interface-element, de omringende interface en de inhoud die door plaatsaanduidingen wordt weergegeven uit te leggen. Beschouw die details als praktische vertaalcontext. Code-along: Verken lokalisatie met Xcode

Maak vage opmerkingen duidelijk en bruikbaar

De volgende voorbeelden horen bij een illustratieve Mac-app om vormen te bekijken. Elke verbeterde opmerking beschrijft een verondersteld, expliciet interfacegedrag. Pas die beschrijving aan het daadwerkelijke besturingselement aan voordat je de formulering gebruikt.

Brontlabel Zwakke opmerking Bruikbaardere opmerking
Shapes Label voor vormen. Navigatie-item in de zijbalk dat de lijst met geometrische vormen opent. Meervoudig zelfstandig naamwoord.
Round Vormtekst. Categoriekop boven voorbeelden van vormen met gebogen omtrekken. Bijvoeglijk naamwoord dat de vormen beschrijft.
Expand Knoptitel. Knop onder een vormvoorbeeld waarmee de details onder het voorbeeld worden weergegeven. Werkwoord dat een actie uitdrukt.
Selected Selectielabel. Status naast de vorm die momenteel voor het voorbeeld is gekozen. Beschrijft de huidige status van de vorm.

De zwakke versies herhalen wat de vertaler al kan zien. De sterkere versies geven ontbrekende verbanden: welk object het bijvoeglijk naamwoord beschrijft, welke inhoud de knop toont of welk item een bepaalde status heeft.

In het Engels benoemt een zelfstandig naamwoord iets, beschrijft een bijvoeglijk naamwoord iets en geeft een gebiedende wijs opdracht tot een actie. Deze verschillen helpen om beknopte interfaceformuleringen toe te lichten. In dit voorbeeld beschrijft Selected bijvoorbeeld een bestaande status; Select op een knop zou een actie vragen. Geef aan welke interpretatie de interface vereist.

Houd opmerkingen concreet. Leg bij Expand uit of het besturingselement detailtekst toont, een voorbeeld vergroot of een groep in de zijbalk opent. De handeling benoemen is nuttiger dan zeggen dat iets groter wordt.

Leg geen onnodige Engelse opmaakregels op. Als de interface een beknopte categoriekop nodig heeft, vermeld dat dan. Verzin geen vaste tekenlimiet en vereis niet dat de vertaling de Engelse woordvolgorde aanhoudt. Leg alleen een echte lay-outbeperking vast als je weet dat die van toepassing is.

Opmerkingen voor vertalers toevoegen in SwiftUI

Apple documenteert de parameter comment: van Text als een manier om vertaalaanwijzingen toe te voegen. Als de handige tekenreeksinitializer van een besturingselement niet de benodigde opmerking biedt, gebruik dan de inhoudsopbouwfunctie met een expliciete Text-weergave. Apple toont dit patroon voor Label en legt uit dat veel SwiftUI-besturingselementen dit ondersteunen. Weergaven voorbereiden op lokalisatie

Het volledige voorbeeld hieronder is een kleine macOS-app in SwiftUI. Maak in Xcode een macOS-appproject met SwiftUI, stel de implementatiedoelversie in op macOS 13 of hoger en vervang de gegenereerde code voor de app en de inhoudsweergave door dit ene bestand. Behoud slechts één app-ingangspunt. Het voorbeeld gebruikt vaste, synthetische namen en toont een detailzin wanneer de gebruiker op Expand klikt.

import SwiftUI

@main
struct ShapeCommentDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ShapeBrowserView()
        }
    }
}

struct ShapeBrowserView: View {
    @State private var showsDetails = false

    private let shapeName = "Circle A"
    private let collectionName = "Shape Set A"

    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            Text(
                "Round",
                comment: "Category heading above previews of shapes with curved outlines. Adjective describing the shapes."
            )
            .font(.headline)

            Circle()
                .fill(Color.blue)
                .frame(width: 80, height: 80)

            Text(
                "\(shapeName) in \(collectionName)",
                comment: "Caption below a shape preview. The first value is the shape name; the second is the collection containing it. Sample names: Circle A and Shape Set A."
            )

            Button {
                showsDetails = true
            } label: {
                Text(
                    "Expand",
                    comment: "Button below a shape preview that reveals its details beneath the preview. Verb expressing an action."
                )
            }
            .disabled(showsDetails)

            if showsDetails {
                Text(
                    "A shape with a curved outline.",
                    comment: "Detail sentence revealed below the preview after clicking Expand. Describes the displayed circle."
                )
            }
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 300)
    }
}

Dit voorbeeld is gecontroleerd aan de hand van de gedocumenteerde API-patronen; het is hier niet gecompileerd of uitgevoerd omdat de beschikbare omgeving geen Swift-toolchain heeft.

Voor gebruikersgerichte tekenreeksen die buiten een SwiftUI-weergave worden gemaakt, documenteert Apple String(localized:comment:). Gebruik het commentaarargument van de lokalisatie-API om de context aan het bericht toe te voegen. Apple ondersteunt ook een aparte opzoeksleutel en standaardbronwaarde als die van elkaar moeten verschillen. De tekst van je app voorbereiden op vertaling

Leg ingevoegde waarden uit aan de hand van hun betekenis en onderlinge relatie

Het bijschrift in het voorbeeld bevat twee Swift-interpolaties: \(shapeName) en \(collectionName). Swift-interpolatie voegt de waarden van expressies in een tekenreeksliteral in. De variabelenamen horen bij de broncode; de uitleg moet ook begrijpelijk zijn voor iemand die die namen niet kan zien. Tekenreeksen en tekens

Met de getoonde synthetische waarden luidt het Engelse bijschrift Circle A in Shape Set A. De opmerking licht zowel de volgorde van de ingevoegde waarden als hun relatie toe: de ene benoemt de vorm en de andere de collectie waarin die voorkomt. Dat geeft bruikbaardere informatie dan alleen twee tekenreeksargumenten beschrijven.

Stel jezelf bij het beoordelen van een bericht met interpolaties drie vragen:

  1. Wat voor soort inhoud kan op elke positie verschijnen: een naam, een aantal of een ander type waarde?
  2. Hoe verhouden de waarden zich tot elkaar?
  3. Blijft de opmerking correct voor elke waarde die de app kan aanleveren?

Geef duidelijk aan dat voorbeelden slechts voorbeelden zijn. Hier illustreren Circle A en Shape Set A de rollen van de argumenten. Ze leggen geen verplichte vertaling of uitputtende lijst met mogelijke namen vast.

Voor aantallen is een aparte implementatiebeslissing nodig. Als je later een bijschrift zoals 3 shapes toevoegt, kan een opmerking uitleggen wat er wordt geteld, maar de grammaticale varianten horen in de catalogus. Apple documenteert het gebruik van Vary by Plural voor geïnterpoleerde aantallen, inclusief afzonderlijke Engelse vormen zoals 1 item en 2 items. Tekst lokaliseren en variëren met een stringcatalogus

Opmerkingen zoeken en bekijken in Xcode

Volg Apples gedocumenteerde workflow om de broncodeopmerkingen aan de catalogus te koppelen:

  1. Kies File > New > File from Template.
  2. Filter op string, selecteer String Catalog onder Resource en maak die aan met de standaardnaam Localizable.
  3. Kies Product > Build om lokaliseerbare tekenreeksen te extraheren.
  4. Selecteer Localizable.xcstrings in de projectnavigator.
  5. Kies Editor > Assistant en selecteer vervolgens een sleutel om de broncode ernaast in de catalogus te bekijken. Tekst lokaliseren en variëren met een stringcatalogus

Controleer of de opmerking in de catalogus overeenkomt met het daadwerkelijke gebruik. In het voorbeeld moet Round een categoriekop beschrijven en moet Expand uitleggen dat details worden weergegeven. Ontbreekt er een tekenreeks, controleer dan of de code een lokaliseerbare API gebruikt en of Use Compiler to Extract Swift Strings is ingeschakeld. Apple noemt deze bouwinstelling noodzakelijk voor het extraheren van Swift-tekenreeksen door de compiler. Ontdek String Catalogs

Apple ondersteunt ook het rechtstreeks bewerken van context in de opmerkingenkolom van de String Catalog. Automatische generatie van opmerkingen is geïntroduceerd in Xcode 26; de huidige documentatie beschrijft hoe je met Control ingedrukt op een sleutel klikt en Generate Comment kiest. Als die optie in jouw configuratie niet beschikbaar is, voeg dan een opmerking toe in de code of voer die in de catalogus in. Code-along: Verken lokalisatie met Xcode, Tekst lokaliseren en variëren met een stringcatalogus

Controleer gegenereerde formuleringen aan de hand van het interfacegedrag. Een beschrijving die een knop correct identificeert, moet mogelijk nog verduidelijken om welk object of resultaat het gaat. In dit voorbeeld is het nuttig om duidelijk te maken dat Expand een detailzin onder het voorbeeld toont.

Bepalen of twee identieke labels dezelfde context kunnen delen

Dezelfde Engelse spelling betekent niet automatisch dezelfde betekenis. Stel dat een ander scherm Round gebruikt als actie om een numerieke waarde af te ronden. Als je dat gebruik combineert met de categoriekop voor vormen, moet één catalogusitem twee verschillende grammaticale rollen beschrijven.

Apple legt uit dat een lokaliseerbare tekenreeks een opzoeksleutel heeft en bij een tabel hoort; sleutels zijn uniek binnen hun tabel. De Swift-documentatie van Apple biedt ook een ondersteunde manier om een afzonderlijke sleutel met een standaardbronwaarde te gebruiken. Gebruik afzonderlijke sleutels wanneer de betekenissen onafhankelijke vertalingen vereisen, ook als de Engelse weergavetekst overeenkomt. Ontdek String Catalogs, De tekst van je app voorbereiden op vertaling

Een praktische beslisregel is om na te gaan of één opmerking elk gebruik correct kan uitleggen. Als de betekenis en de rol in de gebruikersinterface consistent blijven, kan gedeelde context geschikt zijn. Moet de uitleg ongerelateerde handelingen beschrijven, heroverweeg dan de sleutelstructuur. Dit is een ontwerpconclusie op basis van Apples model met sleutels en tabellen, geen regel die voorschrijft dat elk besturingselement een eigen tekenreeks nodig heeft.

Lees de opmerking bij een label zonder de broncode voordat je het overdraagt. De opmerking moet de vertaler helpen de bedoelde betekenis te herkennen, de tekst conceptueel in de interface te plaatsen en eventuele ingevoegde inhoud te begrijpen. Pas de opmerking aan zodra het gedrag of de rol van het label verandert, zodat de uitleg blijft overeenkomen met wat de gebruiker in de interface ziet.

Bronnen