Geef zowel de resourcebundel als de stringstabel door om een lokalisatiesleutel van een framework op te lossen. Deze handleiding laat zien hoe je een label van een framework correct in een Mac-app weergeeft en vervolgens controleert of de tekst uit de tabel komt en niet uit de terugvaltekst.

De taak is bewust klein gehouden: geef het synthetische label Open panel weer uit de catalogus Panel.xcstrings van een framework. Je hebt een Mac-appproject in Xcode nodig en een frameworkdoel dat je zelf beheert. Het hoofdvoorbeeld gebruikt Xcode 26 of hoger en is gericht op macOS 12 of hoger; Apple documenteert dat de initializer voor gelokaliseerde strings beschikbaar is vanaf macOS 12. Documentatie van de Swift-initializer.

Bepaal de bundel, tabel en sleutel voordat je code wijzigt

Beschouw een gelokaliseerd bericht als een opzoekactie met drie expliciete coördinaten. De bundel geeft aan wie de resource beheert, de tabel geeft een groep strings binnen die bundel aan en de sleutel identificeert een item in die tabel. De lokalisatie-API’s van Apple behandelen de bundel en de tabel afzonderlijk, omdat zowel frameworks als appdoelen stringresources kunnen bevatten. De tekst van je app voorbereiden op vertaling.

Noteer voor dit voorbeeld de volgende afspraken voordat je de catalogus opent. Dit zijn illustratieve namen, geen namen die Apple voorschrijft.

Onderdeel Voorbeeldwaarde Doel
Resource-eigenaar Je frameworkdoel Bevat de catalogus
Catalogusbestand Panel.xcstrings Slaat de brontekst en vertalingen van de tabel op
Tabelargument Panel Selecteert die catalogus zonder de extensie
Sleutel PANEL_OPEN_ACTION Identificeert het bericht
Engelse bronwaarde Open panel Levert leesbare interfacetekst
Opmerking Label for the action that opens the panel. Legt het gebruik van het bericht uit

Met table: \"Panel\" selecteer je de tabel die wordt weergegeven door Panel.xcstrings. Als je de tabel niet opgeeft, wordt Localizable geselecteerd. Als je de bundel niet opgeeft, zoekt de stringinitializer in de hoofdbundel van de app. Voor een overeenkomende sleutel in een frameworkcatalogus heb je dus zowel de bundel van het framework als de juiste tabel nodig. Parameters voor gelokaliseerde strings in Swift.

Zo krijg je een handige volgorde voor het opsporen van problemen: controleer eerst de eigenaar, dan de tabel en vervolgens het item. Zoeken naar andere schrijfwijzen van de sleutel lost niets op als de opzoekactie naar de resources van de app verwijst terwijl het bericht bij een framework hoort.

Voeg de stringcatalogus toe aan het frameworkdoel

Kies in Xcode File > New > File from Template, selecteer het platform, filter op string en kies String Catalog. Noem het bestand Panel. Zorg ervoor dat de catalogus bij het frameworkdoel hoort, naast de frameworkbroncode die ernaar verwijst. Met de catalogusworkflow van Apple kun je aangepaste catalogusnamen gebruiken; in de frameworkdemonstratie van Apple wordt de catalogus in het frameworkdoel gemaakt. Tekst lokaliseren en variëren met een stringcatalogus, Frameworklokalisatiedemonstratie van Apple.

In het voorbeeld wordt een semantische sleutel gebruikt, zodat de zichtbare tekst niet tegelijk als sleutel dient. Met PANEL_OPEN_ACTION als identificatie en Open panel als standaardwaarde maakt de code beide onderdelen expliciet. Apple ondersteunt deze aanpak met de initializer die een statische sleutel en een afzonderlijke standaardlokalisatiewaarde accepteert. Swift-initializer met statische sleutel.

Bouw het frameworkdoel nadat je de onderstaande broncode hebt toegevoegd. Tijdens builds ontdekt Xcode aanroepen van lokaliseerbare API’s en werkt het de betreffende catalogi bij. Open Panel.xcstrings en controleer of deze PANEL_OPEN_ACTION, de Engelse bronwaarde Open panel en de toelichtende opmerking bevat. Ontbreekt het item, controleer dan of de broncode aan het juiste doel is gekoppeld en of het doel met die broncode is gebouwd. Je kunt ook Editor > Assistant gebruiken om de code te bekijken die bij een catalogusitem hoort. Een stringcatalogus vullen en bekijken.

Los het bericht op binnen het framework

Plaats dit volledige bronbestand in het frameworkdoel. Het definieert de gelokaliseerde string en een klein SwiftUI-label dat de omvattende Mac-app kan weergeven. Ook bevat het een diagnostische methode die je in het volgende gedeelte gebruikt. De code is gecontroleerd aan de hand van de gedocumenteerde signaturen van Apple, maar is hier niet uitgevoerd omdat er geen Swift-compiler beschikbaar was.

import Foundation
import SwiftUI

public enum PanelMessages {
    public static var openPanel: String {
        String(
            localized: "PANEL_OPEN_ACTION",
            defaultValue: "Open panel",
            table: "Panel",
            bundle: #bundle,
            comment: "Label for the action that opens the panel."
        )
    }

    public static func lookupReport() -> String {
        let missingMarker = "__PANEL_LOOKUP_MISSING__"
        let result = #bundle.localizedString(
            forKey: "PANEL_OPEN_ACTION",
            value: missingMarker,
            table: "Panel"
        )

        if result == missingMarker {
            return "No entry resolved from the selected bundle and table."
        }

        return "Resolved table value: \(result)"
    }
}

public struct PanelActionLabel: View {
    public init() {}

    public var body: some View {
        Text(verbatim: PanelMessages.openPanel)
    }
}

De expressie #bundle wordt geëvalueerd op de plek waar je die schrijft. Binnen deze frameworkbroncode levert die de bundel van het frameworkdoel. Verplaats je dezelfde expressie naar broncode van het appdoel, dan levert die de bundel van de app. Voor een Swift Package-doel documenteert Apple dat de macro de resourcebundel van het doel levert. Houd de opzoekactie bij de resources die het doel beheert. De bundelmacro van Foundation.

De declaratie retourneert een gewone String waarvan de lokalisatie al is opgelost. De weergave gebruikt Text(verbatim:) om dat resultaat expliciet weer te geven. De openbare weergave is alleen een label; voeg het toe aan een bestaande appweergave op de plek waar de tekst moet verschijnen.

Gebruik een frameworkklasse als de bundelmacro niet beschikbaar is

Apple ondersteunt ook het vinden van een frameworkbundel via een klasse die in dat framework is gedefinieerd. Voor een conventioneel framework met eigen resources is het volgende een volledig alternatief voor de berichtprovider. Gebruik dit in plaats van de eerdere declaratie van PanelMessages en behoud de hierboven beschreven catalogus- en implementatievereisten.

import Foundation

private final class PanelBundleAnchor: NSObject {}

public enum PanelMessages {
    public static var openPanel: String {
        String(
            localized: "PANEL_OPEN_ACTION",
            defaultValue: "Open panel",
            table: "Panel",
            bundle: Bundle(for: PanelBundleAnchor.self),
            comment: "Label for the action that opens the panel."
        )
    }
}

De klasse die als anker dient, moet worden gecompileerd in het framework waarvan je de resources wilt gebruiken. Apple documenteert dat Bundle(for:) de bundel retourneert die bij de opgegeven klasse hoort, waaronder de frameworkbundel indien van toepassing. Een anker dat in de app is gecompileerd, verwijst naar de app. Selecteer voor pakketresources of resources in een afzonderlijke bundel de daadwerkelijke resourcebundel; de locatie van een klasse alleen bepaalt niet wie die resources beheert. Initializer voor bundels op basis van een klasse, Resourcebundel selecteren met de macro.

Controleer of leesbare tekst uit een geslaagde opzoekactie komt

Dat je Open panel op het scherm ziet, bewijst niet dat het opzoeken in de catalogus is geslaagd. De defaultValue van de initializer wordt geretourneerd als het opzoeken mislukt. Dezelfde zichtbare tekst kan dus zowel op een geslaagde opzoekactie als op terugvaltekst wijzen. Dit gedrag is nuttig voor leesbare interfacetekst, maar kan tijdens de ontwikkeling een onjuiste bundel of tabel verhullen. Gedrag van de standaardwaarde in Swift.

De methode lookupReport() uit het eerste bronbestand neemt die dubbelzinnigheid weg. De methode voert een opzoekactie uit met een herkenbare terugvalmarkering die niet als echte cataloguswaarde mag worden gebruikt. Bekijk de geretourneerde waarde in de actieve app of vanuit een bestaande debugcontext. Als er geen item wordt gevonden, onderzoek dan de geselecteerde resources voordat je vertalingen aanpast.

Deze diagnose volgt rechtstreeks uit het gedocumenteerde gedrag van Bundle.localizedString(forKey:value:table:): als een sleutel ontbreekt en de opgegeven terugvalwaarde niet leeg is, retourneert de methode die waarde. Bij een ontbrekende sleutel en een nil- of lege terugvalwaarde retourneert de methode de sleutel zelf. De markering maakt het makkelijker om een fout te onderscheiden van echte brontekst. Retourwaarden van gelokaliseerde bundelstrings).

Waarneming Volgende controle
De diagnose retourneert het bericht dat het item ontbreekt Controleer of de catalogus in de geselecteerde bundel is gebouwd en controleer daarna Panel en PANEL_OPEN_ACTION
De diagnose vindt een onverwachte waarde Bekijk dat specifieke item in de geselecteerde tabel en de taal die tijdens de huidige uitvoering wordt gebruikt
De diagnose vindt de juiste waarde, maar de interface wijkt af Controleer welke waarde de interface daadwerkelijk weergeeft
De Engelse bronwaarde verschijnt tijdens een uitvoering in een andere taal Controleer de vertaling van het item en de uitvoeringsconfiguratie; een geslaagde opzoekactie bewijst op zichzelf niet dat de gevraagde vertaling bestaat

Deze tabel is een volgorde voor het oplossen van problemen die is afgeleid van de afspraken voor de opzoekactie. Een geslaagde markeringstest bevestigt dat de opzoekactie een item heeft gevonden, maar bewijst niet dat alle ondersteunde talen een voltooide vertaling hebben. Controleer het vinden van resources en de volledigheid van vertalingen afzonderlijk.

Test het label in de geselecteerde taal van de Mac-app

Als je app extra talen ondersteunt, selecteer dan de gewenste taal in de zijbalk van de catalogus en voer de vertaling in het tekstveld van dat item in. Test vervolgens met de omvattende Mac-app. Apple documenteert hoe je vertalingen rechtstreeks in de cataloguseditor invoert en hoe de vertaalstatus van elk item tijdens het werk wordt bijgewerkt. Vertalingen toevoegen aan een stringcatalogus.

Stel de debuguitvoering als volgt in: kies Product > Scheme > Edit Scheme, selecteer Run en open Options. Stel App Language in op een taal die het project ondersteunt, sluit de editor en voer de Mac-app opnieuw uit. Kies System Language als je wilt dat de uitvoering de taalinstelling van het systeem volgt. Lokalisaties testen tijdens het uitvoeren van je app.

Gebruik het argument locale: van de stringinitializer niet als vervanging voor deze taaltest. Apple documenteert dat dit argument de lokalisatie van geïnterpoleerde waarden, zoals getallen, bepaalt en de taal voor het opzoeken van de gelokaliseerde string niet wijzigt. Het voorbeeld laat dit argument weg omdat het label geen geïnterpoleerde waarden bevat. De parameter voor de landinstelling van gelokaliseerde strings in Swift.

Houd de uiteindelijke afspraken klein en expliciet: het framework beheert Panel.xcstrings, de opzoekactie selecteert Panel en PANEL_OPEN_ACTION identificeert het label. Controleer het item met de diagnose en controleer daarna de weergegeven vertaling in de gekozen uitvoeringstaal van de app. Zo kun je de resource-opzoekactie corrigeren voordat je tijd besteedt aan tekst die de app misschien helemaal niet inleest.

Bronnen