En användbar översättarkommentar förklarar vad en etikett betyder, var den visas och vad som händer när någon använder den. Den här guiden visar hur du skriver och kopplar sådana kommentarer i Xcode för en enkel formbläddrare för Mac med syntetiska engelska etiketter.

Vad bör en översättarkommentar förklara?

Börja med det beslut som översättaren behöver fatta. En kort etikett som Round lämnar dess grammatiska funktion och avsedda betydelse oklar. En kommentar kan ange att det är ett adjektiv som beskriver en formkategori och förklara att det visas ovanför en grupp förhandsvisningar. Apple rekommenderar kommentarer som klargör var och hur en sträng används i gränssnittet. Upptäck strängkataloger

För den som förbereder etiketterna i en Mac-app för översättning är den konkreta uppgiften att omvandla varje tvetydig sträng till en kort, fristående förklaring. Översättaren ska kunna förstå syftet utan att navigera i källkoden.

Använd den här skrivguiden i fyra delar. Det är en redaktionell metod som bygger på Apples vägledning, inte ett kommentarsformat som Apple kräver:

Del Fråga att besvara Exempel på detalj
Betydelse Vad syftar källtexten på? Round beskriver former med böjda konturer.
Funktion i gränssnittet Vilken typ av gränssnittstext är detta? En kategorirubrik ovanför formförhandsvisningar.
Beteende eller plats Vad händer, eller vad omger texten? Expand visar detaljer under förhandsvisningen.
Variabelt innehåll Vad kan varje infogat värde innehålla? Det första värdet är ett formnamn, det andra ett samlingsnamn.

Ta bara med delar som påverkar tolkningen. En statisk rubrik behöver ingen förklaring av en åtgärd. För en knapp är det bra att tydligt beskriva vad som händer när man klickar på den. För ett meddelande med två infogade namn behöver relationen mellan namnen förklaras.

Apple rekommenderar särskilt att man förklarar gränssnittselementet, det omgivande gränssnittet och innehållet som representeras av platshållare. Se de uppgifterna som praktisk översättningskontext. Kodgenomgång: Utforska lokalisering med Xcode

Förvandla vaga kommentarer till användbara beskrivningar av strängarna

Följande exempel hör till en illustrativ formbläddrare för Mac. Varje förbättrad kommentar beskriver ett antaget, uttryckligt beteende i gränssnittet. Anpassa beteendet till den faktiska kontrollen innan du använder formuleringen.

Källetikett Svag kommentar Mer användbar kommentar
Shapes Etikett för former. Navigeringsobjekt i sidofältet som öppnar listan över geometriska former. Substantiv i plural.
Round Formtext. Kategorirubrik ovanför förhandsvisningar av former med böjda konturer. Adjektiv som beskriver formerna.
Expand Knapprubrik. Knapp under en formförhandsvisning som visar dess detaljer under förhandsvisningen. Verb som uttrycker en åtgärd.
Selected Urvalsetikett. Status bredvid den form som för närvarande valts för förhandsvisningen. Beskriver formens aktuella tillstånd.

De svaga versionerna upprepar sådant som översättaren redan kan se. De starkare versionerna tillför de relationer som saknas: vilket objekt adjektivet beskriver, vilket innehåll knappen visar eller vilket objekt som har ett visst tillstånd.

På engelska benämner ett substantiv något, ett adjektiv beskriver något och ett imperativverb uppmanar till en handling. Skillnaderna hjälper till att förklara kortfattade formuleringar i gränssnittet. I den här illustrationen beskriver till exempel Selected ett befintligt tillstånd; Select på en knapp skulle uppmana till en handling. Ange vilken tolkning gränssnittet kräver.

Håll kommentarerna konkreta. För Expand kan du förklara om kontrollen visar detaljtext, förstorar en förhandsvisning eller öppnar en grupp i sidofältet. Att namnge åtgärden är mer användbart än att säga att den gör något större.

Undvik att införa onödiga engelska formateringsregler. Om gränssnittet behöver en kortfattad kategorirubrik, säg det. Hitta inte på en fast teckenbegränsning och kräv inte att översättningen följer engelsk ordföljd. Beskriv en verklig begränsning i layouten endast om du vet att den gäller.

Lägg till översättarkommentarer i SwiftUI

Apple beskriver parametern comment: på Text som ett sätt att lägga till översättningstips. När en bekväm stränginitierare för en kontroll inte ger den kommentar du behöver kan du använda dess innehållsbyggare med en uttrycklig Text-vy. Apple visar det här mönstret för Label och förklarar att många SwiftUI-kontroller stöder det. Förbereda vyer för lokalisering

Det fullständiga exemplet nedan är en liten macOS-app med SwiftUI. Skapa ett macOS-approjekt i Xcode med SwiftUI, ange macOS 13 eller senare som distributionsmål och ersätt den genererade app- och innehållsvykoden med den här enda filen. Behåll bara en startpunkt för appen. Exemplet använder fasta, syntetiska namn och visar en detaljmening när användaren klickar på Expand.

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)
    }
}

Exemplet har granskats mot de dokumenterade API-mönstren. Det har inte kompilerats eller körts här eftersom den tillgängliga miljön saknar Swift-verktygskedja.

För användarvända strängar som skapas utanför en SwiftUI-vy beskriver Apple String(localized:comment:). Använd lokaliserings-API:ets kommentarsargument för att koppla kontexten till meddelandet. Apple stöder också en separat uppslagsnyckel och ett standardvärde i källspråket när de behöver skilja sig åt. Förbereda appens text för översättning

Förklara infogade värden utifrån betydelse och relation

Bildtexten i exemplet innehåller två Swift-interpoleringar: \(shapeName) och \(collectionName). Swift-interpolering infogar värdena från uttryck i en strängliteral. Variabelnamnen hör till källkoden; förklaringen ska ändå vara begriplig för någon som inte kan se namnen. Strängar och tecken

För de syntetiska värdena som visas lyder den engelska bildtexten Circle A in Shape Set A. Kommentaren förklarar både ordningen på de infogade värdena och hur de hänger ihop: det ena anger formen och det andra anger samlingen den tillhör. Det ger mer användbar information än att bara beskriva två strängargument.

Ställ tre frågor när du granskar ett interpolerat meddelande:

  1. Vilken typ av innehåll kan visas på varje plats: ett namn, ett antal eller något annat slags värde?
  2. Hur hänger värdena ihop?
  3. Är kommentaren fortfarande korrekt för varje värde som appen kan tillhandahålla?

Ange tydligt att exempel bara är exempel. Här illustrerar Circle A och Shape Set A argumentens funktion. De definierar inte en obligatorisk översättning eller en fullständig lista över möjliga namn.

Antal kräver ett separat implementeringsbeslut. Om du senare lägger till en bildtext som 3 shapes kan en kommentar förklara vad som räknas, men de grammatiska varianterna hör hemma i katalogen. Apple beskriver hur man använder Vary by Plural för interpolerade antal, med separata engelska former som 1 item och 2 items. Lokalisera och variera text med en strängkatalog

Hitta och granska kommentarerna i Xcode

Följ Apples dokumenterade arbetsflöde för att koppla källkommentarerna till katalogen:

  1. Välj File > New > File from Template.
  2. Filtrera efter string, välj String Catalog under Resource och skapa den med standardnamnet Localizable.
  3. Välj Product > Build för att extrahera lokaliseringsbara strängar.
  4. Markera Localizable.xcstrings i projektnavigatorn.
  5. Välj Editor > Assistant och välj sedan en nyckel för att granska dess källa bredvid katalogen. Lokalisera och variera text med en strängkatalog

Kontrollera katalogens kommentar mot den faktiska användningen. I exemplet ska Round förklara en kategorirubrik och Expand beskriva hur detaljer visas. Om en sträng saknas bör du kontrollera att koden använder ett lokaliseringsbart API och att Use Compiler to Extract Swift Strings är aktiverat. Apple anger att den bygginställningen behövs för kompilatorbaserad extrahering av Swift-strängar. Upptäck strängkataloger

Apple stöder också att man redigerar kontexten direkt i strängkatalogens kommentarskolumn. Automatisk kommentarsgenerering introducerades i Xcode 26. I den aktuella dokumentationen beskrivs hur man Ctrl-klickar på en nyckel och väljer Generate Comment. Om alternativet inte är tillgängligt i din konfiguration kan du lägga till en kommentar i koden eller ange den i katalogen. Kodgenomgång: Utforska lokalisering med Xcode, Lokalisera och variera text med en strängkatalog

Granska den genererade formuleringen mot gränssnittets beteende. En beskrivning som korrekt identifierar en knapp kan ändå behöva förtydliga objektet eller resultatet. I det här exemplet är det viktigt att skilja mellan att visa en detaljmening under förhandsvisningen och andra beteenden.

Avgör om två identiska etiketter kan dela kontext

Samma engelska stavning innebär inte att betydelsen är densamma. Anta att en annan skärm använder Round som en åtgärd för att avrunda ett numeriskt värde. Om den användningen slås ihop med rubriken för formkategorin måste en katalogpost beskriva två olika grammatiska funktioner.

Apple förklarar att en lokaliseringsbar sträng har en uppslagsnyckel och tillhör en tabell, och att nycklar är unika inom tabellen. Apples Swift-dokumentation beskriver också ett sätt att använda en separat nyckel med ett standardvärde i källspråket. Använd separata nycklar när betydelserna kräver oberoende översättningar, även om visningstexten på engelska är densamma. Upptäck strängkataloger, Förbereda appens text för översättning

En praktisk tumregel är att fråga om en kommentar kan förklara varje användning korrekt. Om betydelsen och funktionen i gränssnittet förblir desamma kan det vara lämpligt att dela kontext. Om förklaringen måste beskriva orelaterade åtgärder bör du se över nyckelstrukturen. Det här är en designslutsats utifrån Apples modell med nycklar och tabeller, inte en regel om att varje kontroll behöver sin egen sträng.

Läs kommentaren utan källkoden innan du lämnar över en etikett. Den ska göra det möjligt för översättaren att identifiera den avsedda betydelsen, förstå var texten hör hemma i gränssnittet och förstå eventuellt infogat innehåll. Ändra kommentaren när etikettens beteende eller funktion ändras, så att förklaringen fortsätter att beskriva gränssnittet som användaren ser.

Källor