Pour supprimer les clés de localisation inutilisées dans Xcode, considérez les entrées Stale comme des éléments à examiner. Vérifiez la construction des clés à l’exécution avant de les supprimer, conservez les messages dynamiques nécessaires sous forme d’entrées gérées manuellement et testez les écrans concernés de l’app Mac après le nettoyage.

Ce guide s’adresse aux développeurs qui maintiennent une app Mac SwiftUI utilisant des catalogues de chaînes. Il porte sur un nettoyage de catalogue : identifier les messages qui peuvent être supprimés tout en conservant les libellés et les messages de comptage que l’app affiche encore. L’aide à la décision ci-dessous distingue les indices d’extraction du comportement à l’exécution.

Que signifie réellement une clé de localisation obsolète ?

Xcode détecte les chaînes localisables lors des compilations. Apple explique que l’extraction couvre le schéma et la plateforme actifs. Lorsqu’une chaîne précédemment extraite disparaît, Xcode peut supprimer automatiquement une entrée non traduite ; une entrée qui comporte des traductions est conservée et reçoit l’état Stale. Cet état signifie que Xcode ne trouve plus la chaîne dans le code. Apple précise que sa suppression dépend de la confirmation qu’elle n’est plus nécessaire. Découvrir les catalogues de chaînes

En pratique, l’absence d’une référence dans le code source déclenche une investigation. Une recherche exacte de panel.compact peut trouver une référence littérale, mais ne permet pas de déterminer si le code construit cette clé en associant panel. à un mode sélectionné. Examinez à la fois la clé candidate et le code qui produit les clés de recherche.

Utilisez ce tableau de vérification proposé pour chaque candidate. Il s’agit d’un outil d’aide à la décision fondé sur les limites d’extraction documentées, et non d’une fonctionnalité Xcode supplémentaire.

Indices trouvés lors de l’examen Décision Étape suivante
Un écran supprimé était son seul utilisateur ; il ne reste aucun producteur de clé à l’exécution Supprimer la candidate Supprimez l’entrée, puis recompilez et vérifiez le changement
Le code à l’exécution peut encore produire cette clé exacte Conserver Gardez-la en gestion manuelle ou remplacez la recherche par des références localisables explicites
La clé est encore référencée dans une autre cible ou condition de compilation Conserver Compilez et examinez la configuration concernée
Une clé de nom similaire existe dans une autre table Examiner séparément Confirmez la table et le bundle de ressources utilisés par chaque recherche
Aucun utilisateur n’est trouvé, mais le code qui produit la clé n’est pas clair Reporter Suivez le producteur avant de décider de la suppression

Comment établir une base de référence utile dans Xcode ?

Commencez par enregistrer une copie récupérable du catalogue ou validez son état actuel dans le contrôle de versions. Ouvrez ensuite le projet de l’app et sélectionnez le schéma Mac que vous souhaitez examiner. Notez les cibles et les configurations conditionnelles susceptibles de fournir des messages à l’interface concernée ; l’examen restera ainsi lié à un périmètre explicite.

Sélectionnez le catalogue dans le navigateur de projet et choisissez Product > Build. Apple indique que les compilations remplissent et mettent à jour les catalogues de chaînes à partir du texte localisable du code source. Une fois le catalogue sélectionné, choisissez Editor > Assistant, puis sélectionnez une clé pour examiner son emplacement dans le code source. Le catalogue permet également de revenir au code source. Localiser et faire varier du texte avec un catalogue de chaînes

Si certaines chaînes Swift attendues sont absentes, vérifiez que le paramètre de compilation Use Compiler to Extract Swift Strings est activé pour la cible. Apple précise que cette condition est nécessaire à l’extraction par le compilateur. Un catalogue dont l’extraction est incomplète ne constitue pas une bonne base pour décider quoi supprimer. Localiser votre app SwiftUI

Pour chaque candidate, consignez la clé, le catalogue, l’utilisateur présumé et la décision. Recherchez d’abord la clé exacte, puis son préfixe stable et les wrappers de localisation concernés. Examinez les valeurs du modèle et les données de recherche fournies avec l’app qui alimentent ces wrappers. Relancez les compilations pertinentes lorsqu’une autre cible ou condition de compilation modifie le code source inclus.

Ne fusionnez pas des décisions simplement parce que deux entrées affichent le même texte. Les API de localisation d’Apple acceptent des noms de tables, et les ressources situées hors de l’app principale peuvent nécessiter un autre bundle. Suivez la table et le bundle utilisés par la recherche avant de considérer une autre entrée comme un remplacement. Préparer le texte de votre app pour la traduction

Comment préserver les messages référencés dynamiquement ?

Apple documente la gestion manuelle précisément pour les chaînes dont les clés sont construites dynamiquement. Sélectionnez l’entrée nécessaire et utilisez son inspecteur pour la définir comme gérée manuellement. Xcode ne met pas à jour ces entrées et ne les supprime pas lors de la synchronisation des localisations après compilation. Pour ajouter une entrée dynamique manquante, Apple montre également comment créer une chaîne manuelle à l’aide du bouton plus du catalogue. Découvrir les catalogues de chaînes

La gestion manuelle exige une règle de maintenance explicite. Consignez les clés valides à côté du code ou des données qui les sélectionnent, et expliquez leur usage dans les commentaires du catalogue. Lorsqu’un mode pris en charge est supprimé ultérieurement, examinez aussi son entrée manuelle ; l’extraction automatique ne fera pas ce nettoyage à votre place.

Vérifier si SwiftUI effectue réellement une recherche

Une variable String passée à Text s’affiche sans localisation. Pour utiliser une variable comme clé de recherche, Apple documente la création d’une LocalizedStringKey à partir de celle-ci. Un littéral transmis directement à Text suit automatiquement le chemin de localisation. Ces variantes peuvent produire un résultat identique dans la langue source tout en ayant des comportements différents. LocalizedStringKey

L’application de démonstration complète ci-dessous distingue une clé sélectionnée à l’exécution d’un nombre interpolé. Dans un projet d’app Mac SwiftUI temporaire utilisant Xcode 15 ou une version ultérieure et une cible de déploiement macOS 13, remplacez la déclaration d’app générée par ce code. Ne conservez qu’une seule déclaration @main. Le code a été vérifié au regard des API documentées ; il n’a pas été compilé ici, car aucun outil de compilation Swift n’était disponible.

import SwiftUI

@main
struct CatalogReviewDemoApp: App {
    var body: some Scene {
        WindowGroup {
            CatalogReviewView()
        }
    }
}

struct CatalogReviewView: View {
    @State private var compact = true
    @State private var itemCount = 2

    private var selectedKey: String {
        "panel." + (compact ? "compact" : "expanded")
    }

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Toggle("Compact layout", isOn: $compact)

            Text(LocalizedStringKey(selectedKey))

            Text("\(itemCount) items",
                 comment: "Number of items in the sample panel.")

            Button("Add item") {
                itemCount += 1
            }
        }
        .padding()
        .frame(minWidth: 320)
    }
}

Ajoutez Localizable.xcstrings à la cible de l’app. Ajoutez les entrées gérées manuellement panel.compact et panel.expanded, avec les valeurs source Compact panel et Expanded panel. Compilez le projet pour extraire les messages littéraux. La conversion explicite en LocalizedStringKey demande une recherche à l’exécution ; elle ne fournit pas à l’extracteur une déclaration littérale de chaque clé construite possible.

Pour un petit ensemble fini de choix, envisagez de remplacer la construction des clés par des littéraux localisables explicites dans chaque branche. Pour les interfaces personnalisées qui transmettent des messages entre composants, Apple recommande LocalizedStringResource, qui transporte des informations de localisation telles qu’une table, un commentaire et une valeur par défaut. Choisissez la représentation qui permet d’examiner le plus facilement l’ensemble complet des messages pris en charge. Préparer le texte de votre app pour la traduction

Pourquoi les nombres qui changent diffèrent-ils des clés qui changent ?

Dans la démonstration, la sélection d’une disposition modifie la clé du message recherchée par l’app. Modifier itemCount fournit un argument différent à un même message localisable. L’interpolation SwiftUI convertit les valeurs intégrées en espaces réservés de formatage pour la localisation ; le rendu à l’exécution leur fournit leurs valeurs. Localiser votre app SwiftUI

Vous n’avez donc pas besoin de clés distinctes pour les libellés affichés 2 items, 3 items et 4 items. Compilez l’exemple, trouvez le message de comptage extrait, cliquez sur sa clé en maintenant la touche Contrôle enfoncée, puis choisissez Vary by Plural. Pour une localisation source en anglais, saisissez %lld item pour One et %lld items pour Other, en utilisant le format de nombre entier affiché par Xcode. Apple documente ce processus pour les messages de comptage ainsi que l’ajout des variantes plurielles appropriées aux autres localisations prises en charge. Localiser et faire varier du texte avec un catalogue de chaînes

Lors du nettoyage, examinez un message de comptage comme une ressource complète, avec toutes ses variantes. L’absence dans le code source d’une expression affichée telle que 4 items n’indique pas si le message interpolé sous-jacent est utilisé. De même, conserver un modèle de comptage ne préserve pas une clé dynamique sans rapport simplement parce que les deux messages apparaissent dans le même panneau.

Quelles entrées un nettoyage doit-il réellement supprimer ?

Considérons l’examen illustratif de 24 candidates. Ces nombres décrivent un exemple synthétique et ne correspondent pas au résultat mesuré d’un projet.

Résultat de l’examen Entrées Action
Les seuls utilisateurs appartenaient à un panneau supprimé 9 Supprimer après avoir confirmé que le panneau et ses données de recherche ont disparu
Les clés restent accessibles via une sélection à l’exécution 8 Conserver et documenter la gestion manuelle
Les références appartiennent à une autre cible ou à une compilation conditionnelle 5 Conserver et vérifier ce périmètre de compilation
L’origine de la clé reste indéterminée 2 Conserver en attendant l’examen
Total examiné 24 9 candidates à la suppression

Ce calcul rend la décision de nettoyage vérifiable : 24 entrées examinées ne signifient pas 24 suppressions. Pour chacune des neuf candidates à la suppression, conservez une brève justification qui identifie l’utilisateur supprimé et les chemins de recherche à l’exécution vérifiés. Pour les huit entrées dynamiques, consignez l’ensemble des clés autorisées afin que le prochain examen puisse reprendre la décision.

Supprimez uniquement les candidates confirmées, puis examinez les différences du catalogue. Vérifiez que le changement concerne les clés prévues et leurs traductions associées, sans disparition de variantes plurielles ou d’appareil sans rapport. Recompilez les configurations concernées. Si une clé supprimée réapparaît lors de l’extraction, réexaminez son utilisateur avant de la supprimer à nouveau.

Comment vérifier les messages conservés sur votre Mac ?

Utilisez Product > Scheme > Edit Scheme, sélectionnez Run, puis ouvrez Options. Choisissez une localisation prise en charge existante dans App Language, fermez l’éditeur et lancez la destination Mac. Apple documente ces commandes de schéma pour tester les compilations localisées. Répétez l’opération pour les localisations prises en charge par votre app. Tester les localisations lors de l’exécution de votre app

Essayez chaque sélection dynamique autorisée, y compris les deux dispositions de la démonstration. Vérifiez que l’app affiche les valeurs attendues du catalogue plutôt que les identifiants. Pour les messages de comptage, vérifiez des valeurs synthétiques telles que 0, 1, 2 et 12, et contrôlez les catégories plurielles supplémentaires requises par les localisations prises en charge. Il suffit de modifier le nombre initial de l’exemple pour atteindre ces valeurs de test.

Lorsqu’un message conservé s’affiche incorrectement, examinez la clé exacte, la table, le bundle et l’initialiseur Text avant de modifier le catalogue. Le processus plus récent de génération de symboles d’Apple peut aussi faciliter la référence aux ressources manuelles : Xcode 26 a introduit la génération de symboles pour les catalogues de chaînes, activée dans les projets existants avec Generate String Catalog Symbols. Il s’agit d’une voie de refactorisation facultative, et non d’une preuve qu’une ressource manuelle non référencée est inutilisée. Atelier pratique : explorer la localisation avec Xcode

Terminez avec un ensemble réduit et justifiable de suppressions, ainsi qu’une liste documentée des messages dynamiques conservés. Le résultat utile est un catalogue dont les entrées restantes ont des utilisateurs identifiables, tandis que les clés sélectionnées à l’exécution et les messages de comptage formatés fonctionnent toujours dans l’interface Mac.

Sources