Als je een String Catalog-sleutel in Xcode hernoemt, bewaar je het bronbericht afzonderlijk, werk je de verwijzingen in de code bij en controleer je alle bestaande vertalingen en varianten. Voor geëxtraheerde strings biedt Xcode 26 een refactoring voor conversie; alleen een opzoeksleutel wijzigen is niet voldoende.

Deze gids is bedoeld voor iemand die een bestaande SwiftUI Mac-app met een .xcstrings-catalogus onderhoudt. De taak is om sleutels die uit berichten bestaan te vervangen door betekenisvolle identificatiecodes, terwijl de weergegeven tekst en vertalingen intact blijven. Apple documenteert de API’s en de conversieworkflow hieronder, maar garandeert niet dat een willekeurige sleutelwijziging automatisch alle vertalingen overzet.

Wat moet ongewijzigd blijven als een sleutel verandert?

Een lokaliseerbaar bericht bestaat uit meer dan een identificatiecode. Apple beschrijft de sleutel, standaardwaarde, opmerking en stringtabel als afzonderlijke onderdelen. De sleutel identificeert het bericht tijdens runtime; de standaardwaarde levert de brontekst. Een catalogus bevat de vertalingen en metagegevens van een tabel. Behandel een hernoeming als een gecoördineerde wijziging van dat berichtcontract. String Catalogs ontdekken

Leg vóór het bewerken het volgende vast voor elke betrokken invoer. Deze synthetische voorbeelden illustreren een hernoeming; het zijn geen gemeten resultaten.

Onderdeel Hiervoor Beoogd resultaat
Opzoeksleutel Open collection collection.open
Bronbericht Open collection Ongewijzigd
Tabel Localizable Ongewijzigd
Bundel Hoofdbundel van de app Ongewijzigd
Context voor vertalers Knop waarmee de geselecteerde collectie wordt geopend Behouden
Bestaande vertalingen Huidige waarden in elke lokalisatie Behouden
Aantalsargumenten, indien aanwezig Geheel aantal Zelfde type en betekenis
Meervouds- of apparaatsvarianten Bestaande vertakkingen Behouden

Gebruik dit overzicht als vergelijkingshulp. Een geslaagde build bewijst op zichzelf niet dat de vertalingen zijn behouden: de app kan nog steeds een standaardbericht weergeven als een opzoekactie mislukt. SwiftUI documenteert dat een gelokaliseerde sleutel rechtstreeks kan worden weergegeven als er geen overeenkomst in de catalogus is. Bij een semantische sleutel kan daardoor een identificatiecode zoals collection.open in de interface verschijnen. Weergaven voorbereiden voor lokalisatie

Zoek de bron op voordat je de catalogus bewerkt

Open de bestaande catalogus in de projectnavigator van Xcode. Kies Editor > Assistant en selecteer vervolgens de invoer om de bron te inspecteren. Apple documenteert ook het pijltje naast een sleutel en de voorbeeldgebruiken in de Attributes-inspector als manieren om verwijzingen te vinden. Kies voor geëxtraheerde strings na bronwijzigingen Product > Build om de catalogus te synchroniseren. Tekst lokaliseren en variëren met een stringcatalogus

Controleer of de invoer uit code is geëxtraheerd of handmatig wordt beheerd. Apple legt uit dat de broncode bepalend is voor geëxtraheerde berichten: builds synchroniseren de bronwaarden. Een vertaalde invoer die niet langer wordt geëxtraheerd, blijft bestaan als Stale; een onvertaalde invoer kan worden verwijderd. Handmatig beheerde invoeren worden door extractie niet bijgewerkt of verwijderd. Verwijder een oude vertaalde invoer dus niet alleen omdat er een vervanging is verschenen. String Catalogs ontdekken

Maak voordat je verdergaat een herstelbaar controlepunt en vergelijk de betrokken invoer erna met dat controlepunt. Houd de tabel en bundel tijdens deze taak ongewijzigd, zodat er minder mogelijke oorzaken zijn als een vertaling ontbreekt. De lokalisatie-API’s van Apple accepteren tabel- en bundelinformatie, juist omdat die bepalen waar een bericht wordt gevonden. De tekst in je app voorbereiden op vertaling

Gebruik de conversierefactoring van Xcode voor geëxtraheerde strings

Overweeg voor een project dat Xcode 26 of hoger gebruikt om de bestaande geëxtraheerde invoer om te zetten naar een gegenereerd lokaliseerbaar symbool. Apple introduceerde deze workflow in Xcode 26 en demonstreert hoe je tijdens de conversie een sleutel in een semantische naam verandert. Dit is een gedocumenteerde manier om de identificatie en verwijzingen naar een bericht gezamenlijk te wijzigen. Code-along: lokalisatie verkennen met Xcode

  1. Controleer in de buildinstellingen of Generate String Catalog Symbols op Yes staat als dit voor het bestaande project moet worden ingeschakeld.
  2. Selecteer in de cataloguseditor de bestaande sleutel, klik erop terwijl je Control ingedrukt houdt en kies Refactor > Convert Strings to Symbols.
  3. Bekijk het voorbeeld met de gewijzigde catalogussleutel en de betrokken bronlocaties.
  4. Bewerk in de conversie-interface de voorgestelde semantische naam en, waar van toepassing, de argumentnamen.
  5. Vergelijk de huidige en aangepaste code aan de hand van het gemarkeerde voorbeeld en klik vervolgens op Convert.
  6. Bouw het project en vergelijk de resulterende invoer met je controlepunt, inclusief vertalingen en varianten.

Apple documenteert deze conversieopties en toont voorbeelden van gegenereerd gebruik in de Attributes-inspector. Gebruik die voorbeelden in plaats van op basis van leestekens in je gewenste catalogussleutel een Swift-identificatiecode te raden. Gegenereerde symbolen zijn afhankelijk van catalogusinformatie; niet-standaardtabellen introduceren een tabelnaamruimte. Gegenereerde lokaliseerbare symbolen in je code gebruiken

Deze refactoring is specifiek bedoeld voor de overgang van geëxtraheerde strings naar gegenereerde symbolen. De aangehaalde documentatie beschrijft geen universele hernoemingsbewerking voor elke handmatig beheerde invoer of elke externe verwijzing. Als in het voorbeeld een vereiste verwijzing ontbreekt, verwerk die dan expliciet voordat je de vorige sleutel verwijdert.

Behoud extractie als je sleutels en standaardwaarden in code wilt houden

Je kunt ook codegestuurde extractie behouden. Apple ondersteunt expliciet afzonderlijke opzoeksleutels en bronberichten via String(localized:defaultValue:...): het eerste argument levert de sleutel en defaultValue levert de bronstring. Een semantische sleutel kan bijvoorbeeld Open collection als standaardbericht behouden. De tekst in je app voorbereiden op vertaling

De volgende volledige appbron laat dit patroon zien met één statisch label en één geheel aantal. Gebruik een macOS SwiftUI-appdoel met een implementatiedoel van macOS 12 of hoger en vervang de bestaande appbronvermelding in plaats van een tweede declaratie van @main toe te voegen. Voeg Localizable.xcstrings toe aan het appdoel. Het voorbeeld is gecontroleerd aan de hand van de API’s van Apple; het is hier niet gecompileerd omdat er geen Swift-toolchain beschikbaar was.

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

Hier haalt String(localized:...) de gelokaliseerde tekst op voordat de resulterende string wordt weergegeven. Text(verbatim:) maakt die weergavestap expliciet. Apple maakt onderscheid tussen onmiddellijke stringlokalisatie en LocalizedStringResource, dat een opzoekactie voorstelt die kan worden uitgesteld. Voor herbruikbare interfaces die onopgeloste berichten tussen weergaven doorgeven, raadt Apple een lokaliseerbaar type zoals LocalizedStringResource aan. LocalizedStringResource, De tekst in je app voorbereiden op vertaling

Als je een bestaand bericht op deze manier migreert, bouw het project dan om de doelinvoer aan te maken of bij te werken en zet vervolgens de bestaande vertalingen over voordat je de vorige invoer verwijdert. Apple documenteert hoe je vertalingen rechtstreeks invoert door een lokalisatie te selecteren en de bijbehorende taalkolom te bewerken. Behoud bij een gevarieerd bericht elke relevante vertakking in plaats van alleen de tekst op het hoogste niveau te kopiëren. Deze gefaseerde overdracht is een praktische migratieprocedure op basis van de gedocumenteerde bewerkingstools, geen garantie voor automatische hernoeming. Tekst lokaliseren en variëren met een stringcatalogus

Wat is het verschil tussen extractie en runtime-opmaak?

Extractie gebeurt tijdens de ontwikkeling: Xcode vindt ondersteunde lokaliseerbare expressies en werkt de catalogus bij. Runtime-opmaak gebeurt wanneer de app het bericht ophaalt en waarden invoegt. Het aantal 7 in het voorbeeld is een runtimeargument; het mag geen deel worden van de stabiele sleutel.

Houd de integerinterpolatie binnen de lokaliseerbare expressie. Apples String.LocalizationValue ondersteunt interpolatie en verwijst ontwikkelaars die willekeurige identificatiecodes willen gebruiken naar initializers met een statische sleutel en afzonderlijke defaultValue. Eerst een gewone, gerenderde string maken is niet hetzelfde als dat lokaliseerbare bericht en de argumenten ervan behouden. String.LocalizationValue

Als je berichten met grammaticale aantallen nodig hebt, selecteer dan de geëxtraheerde aantalinvoer, klik erop terwijl je Control ingedrukt houdt en kies Vary by Plural. Vul de bronvarianten en de vereiste varianten voor elke bestaande lokalisatie in. Voor een Engelse bron toont Apple One met %lld item en Other met %lld items. Alleen interpolatie toevoegen is niet genoeg om die varianten compleet te maken. Tekst lokaliseren en variëren met een stringcatalogus

Behoud tijdens een hernoeming de typen, posities en betekenissen van argumenten. Als het oude bericht een geheel aantal bevat, verandert vervanging daarvan door een vooraf opgemaakte string ook het opmaakcontract. Voor berichten met opmaakspecificaties maakt Xcode bij gegenereerde symbolen functies met getypeerde parameters aan; inspecteer die signaturen tijdens de conversie. Gegenereerde lokaliseerbare symbolen in je code gebruiken

Controleer of alles behouden is voordat je de oude invoer verwijdert

Gebruik de volgende controles om te bepalen of de taak is voltooid. Zo kun je een catalogusprobleem onderscheiden van een probleem met opzoeken of opmaak.

Controle Verwacht resultaat Onderzoek dit als de controle mislukt
Brontekst Komt overeen met het controlepunt Ontbrekende of gewijzigde standaardwaarde
Bestaande vertalingen Elke vorige waarde is beschikbaar onder de nieuwe sleutel Onvolledige overdracht of verkeerde bestemming
Variantstructuur Alle eerdere meervouds- en apparaatsvertakkingen zijn behouden Alleen een waarde op het hoogste niveau is gekopieerd
Runtime-label Geeft het bedoelde bericht weer Verkeerde sleutel, tabel, bundel of lokalisatie
Synthetische aantallen 0, 1, 7 Waarden worden correct ingevoegd en de vereiste meervoudsvertakkingen werken Niet-overeenkomend argument of variant
Oude verwijzingen Er zijn geen noodzakelijke toepassingen meer Migratie is onvolledig

Als je de Mac-app in een bestaande lokalisatie wilt testen, kies je Product > Scheme > Edit Scheme, selecteer je Run, open je Options en kies je een App Language. Sluit het venster en voer het Mac-doel uit. Herhaal dit voor de lokalisaties die bij de hernoeming betrokken zijn en controleer het daadwerkelijke label en het aantalsbericht. Apple documenteert deze testworkflow op basis van schema’s. Lokalisaties testen bij het uitvoeren van je app

Als de nieuwe sleutel verschijnt maar de vertaling leeg is, ga dan terug naar de vorige invoer en zet de ontbrekende inhoud over. Als de identificatiecode op het scherm verschijnt, controleer je de invoerwaarden van de opzoekactie. Als alleen aantallen mislukken, controleer je de interpolatie en varianten. Verwijder de oude invoer pas nadat de inhoud ervan is verwerkt en de vereiste verwijzingen zijn verplaatst. De afgeronde wijziging hoort de identificatiecode te veranderen, terwijl het bericht, de argumenten en de vertalingen die lezers al te zien krijgen behouden blijven.

Bronnen