När du byter namn på en String Catalog-nyckel i Xcode ska du bevara källmeddelandet separat, uppdatera kodreferenserna och verifiera alla befintliga översättningar och varianter. För extraherade strängar erbjuder Xcode 26 en refaktorering för konvertering; det räcker inte att bara ändra uppslagsnyckeln.

Den här guiden riktar sig till dig som underhåller en SwiftUI-app för Mac med en befintlig .xcstrings-katalog. Uppgiften är att ersätta meddelandeformade nycklar med meningsfulla identifierare och samtidigt behålla den visade texten och översättningarna intakta. Apple dokumenterar API:erna och konverteringsflödet nedan, men garanterar inte att en godtycklig nyckeländring automatiskt överför alla översättningar.

Vad måste förbli oförändrat när en nyckel ändras?

Ett lokaliserbart meddelande består av mer än en identifierare. Apple beskriver dess nyckel, standardvärde, kommentar och strängtabell som separata komponenter. Nyckeln identifierar meddelandet vid körning; standardvärdet anger källtexten. En katalog innehåller en tabells översättningar och metadata. Behandla namnbytet som en samordnad ändring av meddelandets kontrakt. Upptäck String Catalogs

Anteckna följande för varje berörd post innan du redigerar. De här syntetiska exemplen illustrerar ett namnbyte; de är inte uppmätta resultat.

Komponent Före Avsett resultat
Uppslagsnyckel Open collection collection.open
Källmeddelande Open collection Oförändrat
Tabell Localizable Oförändrad
Paket Huvudappens paket Oförändrat
Översättningskontext Knapp som öppnar den valda samlingen Bevarad
Befintliga översättningar Aktuella värden för varje språkversion Bevarade
Räkneargument, om sådana finns Heltalsantal Samma typ och betydelse
Flertals- eller enhetsvarianter Befintliga grenar Bevarade

Använd den här anteckningen som jämförelseunderlag. En lyckad kompilering räcker inte för att fastställa att översättningarna finns kvar: appen kan fortfarande visa ett standardmeddelande om ett uppslag misslyckas. SwiftUI-dokumentationen anger att en lokaliserad nyckel kan visas direkt om ingen matchning hittas i katalogen. Med en semantisk nyckel kan då en identifierare som collection.open visas i gränssnittet. Förbereda vyer för lokalisering

Hitta källan innan du redigerar katalogen

Öppna den befintliga katalogen i Xcodes projektnavigator. Välj Editor > Assistant och markera sedan posten för att granska dess källa. Apple beskriver även pilen bredvid en nyckel och exempel på användning i attributinspektorn som sätt att hitta referenser. För extraherade strängar väljer du Product > Build efter källändringar för att synkronisera katalogen. Lokalisera och variera text med en strängkatalog

Kontrollera om posten extraheras från kod eller hanteras manuellt. Apple förklarar att källkoden styr extraherade meddelanden: kompileringar synkroniserar deras källvärden. En översatt post som inte längre extraheras finns kvar som Stale; en oöversatt post kan tas bort. Manuellt hanterade poster uppdateras eller tas inte bort vid extrahering. Ta därför inte bort en gammal översatt post bara för att en ersättare har dykt upp. Upptäck String Catalogs

Skapa en återställningsbar kontrollpunkt innan du fortsätter och jämför den berörda posten med den efteråt. Behåll tabellen och paketet oförändrade under den här uppgiften så att det finns färre möjliga orsaker till att en översättning saknas. Apples lokaliserings-API:er tar emot information om tabell och paket just eftersom de avgör var ett meddelande hittas. Förbereda appens text för översättning

Använd Xcodes konverteringsrefaktorering för extraherade strängar

Om projektet använder Xcode 26 eller senare kan du överväga att konvertera den befintliga extraherade posten till en genererad lokaliserbar symbol. Apple introducerade det här arbetsflödet i Xcode 26 och visar hur en nyckel får ett semantiskt namn under konverteringen. Det här är ett dokumenterat sätt att ändra hur ett meddelande identifieras och refereras tillsammans. Kodgenomgång: Utforska lokalisering med Xcode

  1. Kontrollera i bygginställningarna att Generate String Catalog Symbols är inställt på Yes om det behöver aktiveras i det befintliga projektet.
  2. Markera den befintliga nyckeln i katalogredigeraren, Ctrl-klicka på den och välj Refactor > Convert Strings to Symbols.
  3. Granska förhandsvisningen som visar katalogens nyckeländring och berörda källkodsställen.
  4. Redigera det föreslagna semantiska namnet och, där det är tillämpligt, argumentnamnen i konverteringsgränssnittet.
  5. Jämför den aktuella och ändrade koden med hjälp av den markerade förhandsvisningen och klicka sedan på Convert.
  6. Bygg projektet och jämför den resulterande posten med kontrollpunkten, inklusive översättningar och varianter.

Apple dokumenterar dessa konverteringsreglage och visar exempel på genererad användning i attributinspektorn. Använd exemplen i stället för att gissa dig till en Swift-identifierare utifrån skiljetecknen i den katalognyckel du vill ha. Genererade symboler beror på kataloginformation, och tabeller som inte är standardtabeller har ett tabellnamnområde. Använda genererade lokaliserbara symboler i koden

Den här refaktoreringen är särskilt avsedd för övergången från extraherade strängar till genererade symboler. Den citerade dokumentationen fastslår inte att det finns en universell namnbytesåtgärd för varje manuellt hanterad post eller extern referens. Om förhandsvisningen utelämnar en nödvändig referens måste du hantera den uttryckligen innan du tar bort den gamla nyckeln.

Behåll extraheringen om du föredrar nycklar och standardvärden i koden

Du kan också behålla kodstyrd extrahering. Apple stöder uttryckligen separata uppslagsnycklar och källmeddelanden med String(localized:defaultValue:...): det första argumentet anger nyckeln och defaultValue anger källsträngen. En semantisk nyckel kan till exempel behålla Open collection som standardmeddelande. Förbereda appens text för översättning

Följande kompletta appkälla visar mönstret med en statisk etikett och ett heltalsantal. Använd ett macOS SwiftUI-appmål med macOS 12 eller senare som distributionsmål och ersätt appens befintliga källfil med appens startpunkt i stället för att lägga till en andra @main-deklaration. Lägg till Localizable.xcstrings i appmålet. Exemplet granskades mot Apples API:er; det kompilerades inte här eftersom en Swift-verktygskedja inte var tillgänglig.

import Foundation
import SwiftUI

@main
struct CatalogRenameDemoApp: App {
    var body: some Scene {
        WindowGroup {
            CatalogRenameDemoView()
        }
    }
}

struct CatalogRenameDemoView: View {
    private let itemCount: Int = 7

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(verbatim: String(
                localized: "collection.open",
                defaultValue: "Open collection",
                comment: "Label for opening the selected collection."
            ))

            Text(verbatim: String(
                localized: "collection.itemCount",
                defaultValue: "\(itemCount) items",
                comment: "Number of items in the selected collection."
            ))
        }
        .padding()
    }
}

Här hämtar String(localized:...) den lokaliserade texten innan den resulterande strängen visas. Text(verbatim:) gör visningssteget uttryckligt. Apple skiljer mellan omedelbar stränglokalisering och LocalizedStringResource, som representerar ett uppslag som kan skjutas upp. För återanvändbara gränssnitt som skickar olösta meddelanden mellan vyer rekommenderar Apple en lokaliserbar typ, till exempel LocalizedStringResource. LocalizedStringResource, Förbereda appens text för översättning

När du migrerar ett befintligt meddelande med det här tillvägagångssättet bygger du projektet för att skapa eller uppdatera målposten och överför sedan de befintliga översättningarna innan du tar bort den gamla posten. Apple dokumenterar hur översättningar anges direkt genom att välja en språkversion och redigera motsvarande språkspalt. För ett varierat meddelande bevarar du varje relevant gren i stället för att bara kopiera texten på toppnivå. Den här stegvisa överföringen är en praktisk migreringsprocedur som bygger på de dokumenterade redigeringsverktygen, inte en garanti för automatiskt namnbyte. Lokalisera och variera text med en strängkatalog

Hur skiljer sig extrahering från formatering vid körning?

Extrahering sker under utvecklingen: Xcode upptäcker lokaliserbara uttryck som stöds och uppdaterar katalogen. Formatering vid körning sker när appen slår upp meddelandet och infogar värden. Exemplet med antalet 7 är ett argument vid körning; det ska inte ingå i den stabila nyckeln.

Behåll heltalsinterpoleringen i det lokaliserbara uttrycket. Apples String.LocalizationValue stöder interpolering och hänvisar utvecklare som vill använda godtyckliga identifierare till initialiserare med en statisk nyckel och separat defaultValue. Att först skapa en vanlig färdigformaterad sträng är inte likvärdigt med att bevara det lokaliserbara meddelandet och dess argument. String.LocalizationValue

Om du vill använda grammatiskt korrekta meddelanden med antal markerar du den extraherade posten för antal, Ctrl-klickar och väljer Vary by Plural. Fyll i källvarianterna och de nödvändiga varianterna för varje befintlig språkversion. För en engelsk källa visar Apple One med %lld item och Other med %lld items. Det räcker inte att bara lägga till interpolering för att skapa de varianterna. Lokalisera och variera text med en strängkatalog

Bevara argumentens typer, positioner och betydelser när du byter namn. Om det gamla meddelandet innehåller ett heltalsantal ändrar du även formateringskontraktet om du ersätter det med en förformaterad sträng. För genererade symboler skapar Xcode funktioner med typade parametrar för meddelanden som innehåller formatspecifikationer; granska signaturerna vid konvertering. Använda genererade lokaliserbara symboler i koden

Verifiera att allt finns kvar innan du tar bort den gamla posten

Använd följande kontroller för att avgöra om arbetet är klart. De skiljer ett katalogproblem från ett problem med uppslag eller formatering.

Kontroll Förväntat resultat Undersök om kontrollen misslyckas
Källtext Stämmer med kontrollpunkten Saknat eller ändrat standardvärde
Befintliga översättningar Alla tidigare värden finns kvar under den nya nyckeln Ofullständig överföring eller fel destination
Variantstruktur Alla tidigare flertals- och enhetsgrenar finns kvar Endast ett värde på toppnivå har kopierats
Etikett vid körning Visar det avsedda meddelandet Fel i nyckel, tabell, paket eller språkversion
Syntetiska antal 0, 1, 7 Värden infogas korrekt och nödvändiga pluralgrenar fungerar Felaktigt argument eller fel variant
Gamla referenser Ingen nödvändig användning återstår Ofullständig migrering

Om du vill testa Mac-appen i en befintlig språkversion väljer du Product > Scheme > Edit Scheme, sedan Run, öppnar Options och väljer App Language. Stäng dialogrutan och kör Mac-målet. Upprepa för språkversionerna som berörs av namnbytet och kontrollera den faktiska etiketten och meddelandet med antal. Apple dokumenterar det här testflödet via schemat. Testa språkversioner när du kör appen

Om den nya nyckeln visas men översättningen är tom går du tillbaka till den tidigare posten och överför det innehåll som saknas. Om identifieraren visas på skärmen granskar du uppslagets indata. Om bara antal inte fungerar granskar du interpoleringen och varianterna. Ta bort den gamla posten först när dess innehåll har tagits om hand och de nödvändiga referenserna har flyttats. Den färdiga ändringen ska ändra identifieraren och samtidigt bevara meddelandet, dess argument och översättningarna som läsarna redan får.

Källor