À partir de Xcode 26, les catalogues de chaînes peuvent générer des accesseurs Swift qui remplacent les clés de localisation saisies manuellement. Ce guide migre le récapitulatif de sélection d’une petite app Mac vers des propriétés et des fonctions typées, puis vérifie ce que le compilateur protège réellement.

La tâche est volontairement limitée : afficher un titre de fenêtre et un récapitulatif contenant deux nombres entiers. Tous les libellés et toutes les valeurs sont synthétiques. Vous allez créer le contrat du catalogue, le relier à SwiftUI, puis vérifier les diagnostics du compilateur et le résultat affiché.

Qu’est-ce qui permet à un accesseur de localisation d’être vérifié à la compilation ?

Apple a introduit la génération native de symboles à partir des catalogues de chaînes dans Xcode 26. Une entrée sans espaces réservés produit une propriété statique ; une entrée avec espaces réservés produit une fonction aux paramètres typés. Les deux renvoient LocalizedStringResource. Les nouveaux projets Xcode 26 activent la génération par défaut ; il peut être nécessaire d’activer le paramètre de compilation dans les projets existants. Atelier pratique : explorer la localisation avec Xcode

Le changement utile se situe au point d’appel. Un littéral chaîne peut désigner une clé de recherche sans faire référence à une déclaration Swift. Un accesseur généré fait référence à un membre qui doit exister, et une fonction générée exige des arguments conformes à sa signature. D’après ces mécanismes documentés, une faute dans le nom d’un membre ou un argument incompatible entraîne une erreur de compilation.

Cette protection a un périmètre précis. Swift peut vérifier que l’accesseur existe et que ses arguments sont compatibles. Il ne peut pas déterminer si le texte décrit l’interface voulue, ni si deux arguments entiers valides correspondent aux bons nombres. Considérez les accesseurs comme une interface de programmation vérifiée pour vos messages.

Configurer une petite app Mac et son contrat de messages

Utilisez Xcode 26 ou une version ultérieure et une cible d’app macOS utilisant SwiftUI. Pour cet exemple, définissez la cible de déploiement sur macOS 15 ou une version ultérieure. Le type sous-jacent LocalizedStringResource est disponible à partir de macOS 13 ; la cible plus récente de l’exemple est un choix préalable, et non la version minimale requise pour ce type. Une ressource représente du texte localisable dont la recherche peut être différée jusqu’au moment où il est nécessaire. LocalizedStringResource

Ajoutez un catalogue via Fichier > Nouveau > Fichier à partir d’un modèle. Sélectionnez String Catalog sous Ressource, nommez-le Workbench et incluez-le dans la cible de l’app. Apple indique que chaque catalogue représente une table ; l’utilisation d’une table distincte permet ici de regrouper les deux messages de l’exemple. Localiser et faire varier le texte avec un catalogue de chaînes

Dans l’éditeur du projet, ouvrez Réglages de compilation, filtrez sur Generate String, puis définissez Generate String Catalog Symbols sur Oui pour la configuration effective de la cible. C’est le commutateur documenté pour les anciens projets. Utiliser les symboles localisables générés dans votre code

Sélectionnez la localisation source anglaise dans Workbench.xcstrings. Ajoutez ces deux entrées à l’aide du bouton + de la barre d’outils de l’éditeur de catalogue. Les commentaires définissent la signification des messages, y compris le rôle de leurs arguments.

Clé Valeur source anglaise Commentaire
TITLE Selection overview Titre au-dessus du récapitulatif de sélection.
SUBTITLE %1$(selectedCount)lld selected; %2$(availableCount)lld available Récapitulatif de sélection. selectedCount correspond au nombre d’éléments sélectionnés ; availableCount correspond au nombre total d’éléments disponibles, éléments sélectionnés inclus.

Pour SUBTITLE, vous pouvez saisir chaque espace réservé à l’aide du menu de complétion de Xcode : tapez %, choisissez l’espace réservé entier, puis nommez-le selectedCount ou availableCount. Apple documente les variables nommées et les paramètres générés pour ces spécificateurs de format. Sélectionnez chaque entrée et examinez Generate Swift Symbol et Example Usages dans l’inspecteur d’attributs. Utiliser les symboles localisables générés dans votre code

Le contrat visé comprend une propriété de titre et une fonction de sous-titre acceptant deux valeurs de type Int. Vérifiez l’orthographe réellement générée dans l’inspecteur avant de continuer : Apple précise que les noms de symboles utilisent à la fois la clé et sa valeur. Les exemples ci-dessous utilisent .Workbench.title et .Workbench.subtitle(selectedCount:availableCount:), conformément au modèle documenté par Apple pour les clés en majuscules. Atelier pratique : explorer la localisation avec Xcode

Ce contrat explicite une distinction utile : availableCount inclut les éléments sélectionnés. Sans ce commentaire, un appelant pourrait raisonnablement comprendre qu’il s’agit du nombre d’éléments restants. Les deux interprétations seraient acceptées par le système de types ; documenter la signification contribue donc à rendre l’accesseur utile.

Utiliser les accesseurs générés dans une fenêtre complète

Après avoir créé le catalogue, choisissez Produit > Compiler. Remplacez la déclaration d’app et la vue de contenu du modèle par le programme suivant, en conservant une seule déclaration @main dans la cible. Ce programme nécessite le catalogue comme ressource ; coller le code Swift dans un fichier autonome ne génère pas ses accesseurs.

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

Avec la localisation source anglaise active, les valeurs d’exemple devraient afficher Selection overview, suivi de 3 selected; 12 available. Les nombres sont fixes afin que vous puissiez vérifier l’emplacement des arguments sans ajouter de code de gestion de la sélection.

Apple indique que les ressources générées peuvent être utilisées dans SwiftUI, notamment dans Text, ainsi qu’avec l’initialiseur String(localized:) de Foundation. Si une interface Mac existante exige un String résolu, convertissez la ressource générée à cette frontière. Atelier pratique : explorer la localisation avec Xcode

Par exemple, voici une fonction d’aide complète à ajouter à la même cible d’app une fois le catalogue créé :

import Foundation

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

Renvoyer LocalizedStringResource depuis votre propre interface préserve une ressource dont la recherche pourra être effectuée plus tard ; renvoyer String la résout à l’exécution de l’initialiseur. Choisissez en fonction des besoins de l’interface destinataire. Apple décrit cette distinction entre recherche différée et immédiate dans la documentation de Foundation. LocalizedStringResource

Les exemples ont été examinés à la lumière de la documentation récupérée. Ils n’ont pas été compilés ici, car l’environnement disponible ne comprend ni exécutable Swift ni Xcode.

Pourquoi le point initial et les étiquettes d’arguments sont importants

Le point initial est la syntaxe de membre implicite de Swift. Elle abrège l’accès à un membre de type lorsque le contexte environnant permet à Swift d’en déduire le type. Il s’agit de syntaxe Swift ordinaire, et non d’un opérateur spécial pour les clés de chaîne. Expressions — expression de membre implicite

Pour les symboles de localisation générés, la table Localizable par défaut expose directement ses membres, tandis qu’une table nommée introduit un espace de noms pour la table. C’est pourquoi cet exemple place .Workbench avant le nom du membre. Apple documente les deux formes. Utiliser les symboles localisables générés dans votre code

Les étiquettes selectedCount: et availableCount: font partie de l’appel de fonction. Swift distingue les étiquettes d’arguments, visibles au point d’appel, des noms de paramètres utilisés à l’intérieur d’une fonction. Lorsqu’un paramètre exige une étiquette, l’appelant doit la fournir. Fonctions — étiquettes d’arguments et noms de paramètres

Des étiquettes lisibles aident à éviter les erreurs, mais les deux arguments ont ici le même type. Inverser les deux valeurs entières reste du Swift valide. Le contrat du message et la vérification du résultat affiché complètent donc le contrôle du compilateur.

Migrer les clés existantes sans en perdre le sens

Pour les chaînes localisables existantes, Apple propose un processus de refactorisation. Sélectionnez des entrées dans le catalogue de chaînes, faites un clic droit en maintenant la touche Contrôle, puis choisissez Refactoriser > Convertir les chaînes en symboles. Examinez l’aperçu, modifiez au besoin les noms de symboles ou de paramètres proposés, puis choisissez Convertir. Utiliser les symboles localisables générés dans votre code

Commencez par migrer un groupe cohérent, par exemple le titre et le récapitulatif de cette fenêtre. Avant d’accepter l’aperçu, comparez l’ancien message et le nouveau contrat : utilisent-ils la même table, décrivent-ils le même élément d’interface et attribuent-ils le même sens à chaque espace réservé ? Examinez les valeurs localisées existantes affectées par un changement de clé au lieu de supposer que la refactorisation en garantit l’exactitude.

Pour un point d’appel que la refactorisation ne met pas à jour, consultez l’utilisation générée dans l’inspecteur du catalogue et remplacez explicitement cette référence. Compilez ensuite et examinez le texte obtenu. Ne supprimez pas l’ancienne entrée avant d’avoir identifié tous ses appelants.

Si la version de Xcode installée ne dispose pas de la génération native, ce processus nécessite une chaîne d’outils plus récente. Apple prend également en charge l’extraction des chaînes depuis les API localisables vers les catalogues, et recommande cette extraction comme processus de départ. Cette méthode reste prise en charge pour gérer la localisation, mais ne fournit pas à elle seule le contrat des accesseurs générés décrit ici. Atelier pratique : explorer la localisation avec Xcode

Vérifier la migration à l’aide d’une courte séquence de diagnostics

Effectuez les vérifications suivantes sur la fenêtre d’exemple. Elles distinguent la protection du compilateur de l’exactitude des messages et de l’intégration des ressources.

  1. Compilez l’exemple inchangé afin d’établir une base de référence fonctionnelle.
  2. Faites temporairement une faute dans le nom du membre de titre, puis compilez. Le membre inexistant devrait produire un diagnostic du compilateur. Rétablissez son nom.
  3. Transmettez temporairement une valeur String là où le sous-titre exige un Int. Compilez pour vérifier l’incompatibilité de types, puis rétablissez l’entier.
  4. Lancez l’app avec selectedCount défini sur 3 et availableCount défini sur 12. Vérifiez que les nombres occupent les positions prévues.
  5. Modifiez uniquement la valeur du titre dans le catalogue pour obtenir Current selection, recompilez et vérifiez le titre affiché. Vérifiez que la signature générée correspond toujours à celle utilisée par votre code.

Si un membre est introuvable de façon inattendue, consultez d’abord l’utilisation générée de l’entrée du catalogue. Vérifiez ensuite le paramètre de génération, l’appartenance du catalogue à la cible et le nom de la table. Un diagnostic du compilateur signale une référence invalide ; ces vérifications permettent de distinguer une faute d’orthographe d’une déclaration générée indisponible.

Enfin, testez l’interface réelle. La procédure documentée par Apple consiste à choisir Produit > Schéma > Modifier le schéma, puis Exécution > Options, où vous pouvez sélectionner la Langue de l’app avant de lancer l’app. Répétez l’opération pour les localisations prises en charge par votre projet. Tester les localisations lors de l’exécution de votre app

Pour vérifier rapidement la mise en page, Xcode propose aussi la Pseudo-langue à texte double, qui allonge le texte localisable afin de révéler les problèmes de dimensionnement. Examinez le récapitulatif dans une fenêtre étroite ; une compilation réussie ne garantit pas que le texte tient dans l’espace disponible. Tester les localisations

Une migration terminée donne à chaque point d’appel un véritable membre Swift, attribue un rôle documenté à chaque variable et préserve un accès vérifié à l’entrée de catalogue visée. Effectuez ensemble les vérifications du compilateur et celles de la fenêtre : les premières valident le contrat de l’accesseur, tandis que les secondes confirment que le lecteur voit le message attendu.

Sources