I Xcode 26 och senare kan String Catalogs generera Swift-accessorer som ersätter manuellt skrivna lokaliseringsnycklar. Den här guiden migrerar en liten Mac-apps urvals-sammanfattning till skrivna egenskaper och funktioner, och kontrollerar sedan vad kompilatorn faktiskt skyddar.

Uppgiften är avsiktligt smal: visa en fönsterrubrik och en sammanfattning som innehåller två heltal. Alla etiketter och värden är syntetiska. Du kommer att skapa katalogkontraktet, ansluta det till SwiftUI, och verifiera både kompilatordsdiagnostik och synlig utdata.

Vad gör en lokaliseringsaccessor kompilatidskontrollerad?

Apple introducerade inbyggd String Catalog-symbolgenerering i Xcode 26. En post utan platshållare producerar en statisk egenskap; en post med platshållare producerar en funktion med skrivna parametrar. Båda returnerar LocalizedStringResource. Nya Xcode 26-projekt aktiverar generering som standard; befintliga projekt kan behöva build-inställningen aktiverad. Code-along: Explore localization with Xcode

Den användbara förändringen är på anropsplatsen. En strängliteral kan stava upp en uppslagsnyckel utan att referera till en Swift-deklaration. En genererad accessor refererar till en medlem som måste existera, och en genererad funktion kräver argument som matchar dess signatur. Från de dokumenterade mekanikerna är den praktiska konsekvensen att en felstavad medlem eller inkompatibelt argument blir ett kompilatorfel.

Det skyddet har ett specifikt omfång. Swift kan kontrollera att accessorn existerar och att dess argument passar. Det kan inte avgöra om formuleringen beskriver det avsedda gränssnittet, eller om två giltiga heltal-argument representerar de korrekta räkningarna. Behandla accessorer som ett kontrollerat programmeringsgränssnitt till dina meddelanden.

Konfigurera en liten Mac-app och dess meddelandekontrakt

Använd Xcode 26 eller senare och ett macOS SwiftUI-appmål. För det här exemplet, sätt distributionsmålet till macOS 15 eller senare. Den underliggande LocalizedStringResource-typen är tillgänglig från macOS 13; exemplets högre mål är ett kravval, inte den minimala versionen av den typen. En resurs representerar lokaliserbar text vars uppslag kan skjutas upp tills det behövs. LocalizedStringResource

Lägg till en katalog via File > New > File from Template. Välj String Catalog under Resource, döp det till Workbench, och inkludera det i appmålet. Apple dokumenterar att varje katalog representerar en tabell; att använda en separat tabell här håller exemplets två meddelanden ihop. Localizing and varying text with a string catalog

I projekteditorn, öppna Build Settings, filtrera för Generate String, och sätt Generate String Catalog Symbols till Yes för målets effektiva konfiguration. Detta är den dokumenterade växeln för äldre projekt. Using generated localizable symbols in your code

Välj den engelska källlokaliseringen i Workbench.xcstrings. Lägg till dessa två poster med katalogeditorns verktygsfältknapp +. Kommentarerna definierar vad meddelandena betyder, inklusive rollerna för deras argument.

Nyckel Engelskt källvärde Kommentar
TITLE Selection overview Rubrik över urvals-sammanfattningen.
SUBTITLE %1$(selectedCount)lld selected; %2$(availableCount)lld available Urvals-sammanfattning. selectedCount är antalet valda; availableCount är det totala antalet tillgängliga, inklusive valda objekt.

För SUBTITLE kan du ange varje platshållare via Xcodes kompletteringsmeny: skriv %, välj heltalsplatshållaren, och ge den namnet selectedCount eller availableCount. Apple dokumenterar namngivna variabler och genererade parametrar för dessa formateringspecificerare. Välj varje post och inspektera Generate Swift Symbol och Example Usages i attributinspektorn. Using generated localizable symbols in your code

Det avsedda kontraktet är en titeleighet och en underrubriksfunktion som accepterar två Int-värden. Kontrollera inspektorns faktiska genererade stavning innan du fortsätter: Apple säger att symbolnamn använder både nyckeln och dess värde. Exemplen nedan använder .Workbench.title och .Workbench.subtitle(selectedCount:availableCount:), följande Apples dokumenterade versal-nyckelmönster. Code-along: Explore localization with Xcode

Det här kontraktet gör en användbar skillnad explicit: availableCount inkluderar valda objekt. Utan den kommentaren kan en anropare rimligtvis tolka det som antalet kvar. Båda tolkningarna skulle typkontrolleras, så att dokumentera innebörden är en del av att göra accessorn användbar.

Använd de genererade accessorerna i ett komplett fönster

Efter att ha skapat katalogen, välj Product > Build. Ersätt malls appdeklaration och innehållsvy med följande program, och behåll exakt en @main-deklaration i målet. Katalogen är en nödvändig resurs för det här programmet; att klistra in Swift-koden i en fristående fil genererar inte dess accessorer.

import Foundation
import SwiftUI

@main
struct SelectionOverviewApp: App {
    var body: some Scene {
        WindowGroup {
            SelectionOverviewView(
                selectedCount: 3,
                availableCount: 12
            )
        }
    }
}

struct SelectionOverviewView: View {
    let selectedCount: Int
    let availableCount: Int

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(.Workbench.title)
                .font(.title2)

            Text(
                .Workbench.subtitle(
                    selectedCount: selectedCount,
                    availableCount: availableCount
                )
            )
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 140)
    }
}

Med den engelska källlokaliseringen aktiv, bör de illustrativa indata visa Selection overview följt av 3 selected; 12 available. Räkningarna är fixerade så att du kan kontrollera argumentplacering utan att införa urvals-hanteringskod.

Apple dokumenterar genererade resurser som användbara i SwiftUI, inklusive Text, och via Foundations String(localized:)-initialiserare. Om ett befintligt Mac-gränssnitt kräver en upplöst String, konvertera den genererade resursen vid den gränsen. Code-along: Explore localization with Xcode

Till exempel är detta en komplett hjälpfunktion att lägga till i samma appmål efter att katalogen existerar:

import Foundation

func selectionSummary(
    selectedCount: Int,
    availableCount: Int
) -> String {
    String(
        localized: .Workbench.subtitle(
            selectedCount: selectedCount,
            availableCount: availableCount
        )
    )
}

Att returnera LocalizedStringResource från ditt eget gränssnitt bevarar en resurs för senare uppslag; att returnera String löser den upp när initialiseringen körs. Välj baserat på vad det mottagande gränssnittet behöver. Apple beskriver denna skjuten-mot-omedelbar-uppslags-distinktion i Foundation-dokumentationen. LocalizedStringResource

Exemplen granskades mot den hämtade dokumentationen. De kompilerades inte här eftersom den tillgängliga miljön saknar Swift-körbar fil eller Xcode.

Varför den inledande punkten och argumentetiketterna betyder något

Den inledande punkten är Swifts implicit-medlems-syntax. Den förkortar åtkomst till en typmedlem när omgivande kontext låter Swift härleda typen. Det är vanlig Swift-syntax, snarare än en speciell strängnyckel-operator. Expressions — Implicit Member Expression

För genererade lokaliseringssymboler exponerar standardtabellen Localizable medlemmar direkt, medan en namngiven tabell introducerar ett tabellnamnområde. Det är därför det här exemplet inkluderar .Workbench före medlemsnamnet. Apple dokumenterar båda former. Using generated localizable symbols in your code

Etiketterna selectedCount: och availableCount: tillhör funktionsanropet. Swift skiljer på argumentetiketter, som visas på anropsplatsen, från parameternamn som används inuti en funktion. När en parameter kräver en etikett måste anroparen ange den. Functions — Function Argument Labels and Parameter Names

Läsbara etiketter hjälper till att förebygga misstag, men båda argumenten här har samma typ. Att byta plats på de två heltalsvärdena förblir giltigt Swift. Meddelandekontraktet och den synliga-utdata-kontrollen kompletterar därför kompilatorn.

Migrera befintliga nycklar utan att förlora deras betydelse

För befintliga lokaliserbara strängar tillhandahåller Apple ett refaktoreringsarbetsflöde. Välj poster i String Catalog, Control-klicka, och välj Refactor > Convert Strings to Symbols. Inspektera förhandsgranskningen, justera de föreslagna symbol- eller parameternamnen om det behövs, och välj Convert. Using generated localizable symbols in your code

Migrera en sammanhängande grupp först, såsom rubriken och sammanfattningen för det här fönstret. Innan du accepterar förhandsgranskningen, jämför det gamla meddelandet och nya kontraktet: använder de samma tabell, beskriver de samma gränssnittselement, och tilldelar de samma betydelse till varje platshållare? Granska eventuella befintliga lokaliserade värden som påverkas av en nyckelförändring snarare än att anta att refaktoriseringen bevisar deras korrekthet.

För en anropsplats som refaktoriseringen inte uppdaterar, använd kataloginspektorens genererade användning och ersätt den referensen explicit. Bygg sedan och inspektera den resulterande texten. Undvik att radera den gamla posten förrän du har tagit hänsyn till dess anropare.

Om din installerade Xcode saknar inbyggd generering, kräver det här arbetsflödet en nyare toolchain. Apple stöder också att extrahera strängar från lokaliserbara API:er in i kataloger, och rekommenderar extraktion som ett startarbetsflöde. Det förblir ett stött sätt att hantera lokalisering, men det levererar inte i sig det genererade-accessor-kontrakt som beskrivs här. Code-along: Explore localization with Xcode

Verifiera migreringen med en liten diagnostiksekvens

Använd följande kontroller på exempel-fönstret. De separerar kompilatorskydd från meddelandekorrekthet och resursintegration.

  1. Bygg det oförändrade exemplet för att etablera en fungerande baslinje.
  2. Felstava tillfälligt titelmedlemmen och bygg. Den icke-existenta medlemmen bör ge en kompilatordsdiagnostik. Återställ den.
  3. Skicka tillfälligt ett String-värde där underrubriken kräver ett Int. Bygg för att kontrollera typmismatch, och återställ sedan heltalet.
  4. Kör med selectedCount satt till 3 och availableCount satt till 12. Bekräfta att numren upptar sina avsedda positioner.
  5. Ändra bara katalogtitelvärdet till Current selection, bygg om, och bekräfta den visade rubriken. Kontrollera att den genererade signaturen förblir den din kod använder.

Om en medlem saknas oväntat, inspektera först katalogpostens genererade användning. Kontrollera sedan genereringsinställningen, katalogens målemedlemskap, och tabellnamnet. En kompilatordsdiagnostik identifierar en misslyckad referens; dessa kontroller hjälper till att skilja ett stavfel från en otillgänglig genererad deklaration.

Slutligen, testa det faktiska gränssnittet. Apples dokumenterade väg är Product > Scheme > Edit Scheme, sedan Run > Options, där du kan välja App Language innan du kör. Upprepa för de lokaliseringar ditt projekt stöder. Testing localizations when running your app

För en tidig layoutkontroll erbjuder Xcode också Double-Length Pseudolanguage, som expanderar lokaliserbar text för att avslöja storleksproblem. Inspektera sammanfattningen vid ett smalt fönsterbredd; lyckad kompilering kan inte fastställa om texten passar. Test localizations

En färdig migrering ger varje anropsplats en riktig Swift-medlem, ger varje variabel en dokumenterad roll, och bevarar en kontrollerad väg till den avsedda katalogposten. Håll kompilatorkontroller och fönsterkontroller tillsammans: de förra validerar accessor-kontraktet, medan de senare bekräftar att läsaren ser det avsedda meddelandet.

Källor