Un commentaire de traducteur utile explique ce que signifie une étiquette, où elle apparaît et ce qui se passe quand quelqu'un l'utilise. Ce guide montre comment rédiger et attacher ces commentaires dans Xcode pour un simple navigateur de formes Mac, en utilisant des étiquettes anglaises synthétiques.

Que doit expliquer un commentaire de traducteur ?

Commencez par la décision que le traducteur doit prendre. Une étiquette courte telle que Round laisse son rôle grammatical et son sens intentionnel flous. Un commentaire peut l'identifier comme un adjectif décrivant une catégorie de formes et expliquer qu'elle apparaît au-dessus d'un groupe d'aperçus. Apple recommande des commentaires qui clarifient où et comment une chaîne est utilisée dans l'interface. Découvrir les catalogues de chaînes

Pour quelqu'un qui prépare les étiquettes d'une app Mac pour la traduction, la tâche concrète consiste à transformer chaque chaîne ambiguë en une petite explication autonome. Le traducteur doit pouvoir en comprendre le but sans naviguer dans le code source.

Utilisez cette aide à la rédaction en quatre parties. Il s'agit d'une méthode éditoriale dérivée des recommandations d'Apple, et non d'un format de commentaire Apple obligatoire :

Partie Question à laquelle répondre Détail d'exemple
Sens À quoi le libellé source fait-il référence ? Round décrit des formes aux contours courbes.
Rôle UI Quel type de texte d'interface est-ce ? Un titre de catégorie au-dessus des aperçus de formes.
Comportement ou emplacement Que se passe-t-il ou qu'est-ce qui l'entoure ? Expand révèle les détails sous l'aperçu.
Contenu variable Que peut contenir chaque valeur insérée ? La première valeur est un nom de forme ; la seconde est un nom de collection.

N'incluez que les parties qui affectent l'interprétation. Un titre statique n'a pas besoin d'explication d'une action. Un bouton bénéficie d'une description claire de ce que fait son clic. Un message avec deux noms insérés a besoin de la relation entre ces noms.

Apple conseille spécifiquement d'expliquer l'élément d'interface, l'interface environnante et le contenu représenté par les espaces réservés. Traitez ces détails comme un contexte de traduction pratique. Code-along : Explorer la localisation avec Xcode

Transformer des commentaires vagues en contrats de message utiles

Les exemples suivants appartiennent à un navigateur de formes Mac illustratif. Chaque commentaire amélioré décrit un comportement d'interface supposé, explicite ; adaptez ce comportement au contrôle réel avant d'utiliser la formulation.

Libellé source Commentaire faible Commentaire plus utile
Shapes Étiquette pour les formes. Élément de navigation de la barre latérale qui ouvre la liste des formes géométriques. Nom pluriel.
Round Texte de forme. Titre de catégorie au-dessus des aperçus de formes aux contours courbes. Adjectif décrivant les formes.
Expand Titre de bouton. Bouton sous un aperçu de forme qui révèle ses détails sous l'aperçu. Verbe exprimant une action.
Selected Étiquette de sélection. État à côté de la forme actuellement choisie pour l'aperçu. Décrit l'état actuel de la forme.

Les versions faibles répètent ce que le traducteur peut déjà voir. Les versions plus fortes fournissent les relations manquantes : quel objet l'adjectif décrit, quel contenu le bouton révèle, ou quel élément a un état particulier.

En anglais, un nom désigne quelque chose, un adjectif décrit quelque chose, et un verbe à l'impératif dirige une action. Ces distinctions aident à expliquer le vocabulaire d'interface compact. Par exemple, Selected dans cette illustration décrit un état existant ; Select sur un bouton demanderait une action. Précisez quelle interprétation l'interface requiert.

Gardez les commentaires concrets. Pour Expand, expliquez si le contrôle révèle du texte de détail, agrandit un aperçu ou ouvre un groupe de la barre latérale. Nommer l'opération est plus utile que de dire qu'elle agrandit quelque chose.

Évitez d'imposer des règles de mise en forme anglaises inutiles. Si l'interface a besoin d'un titre de catégorie concis, dites-le. N'inventez pas de limite de caractères fixe et n'exigez pas que la traduction préserve l'ordre des mots anglais. Documentez une vraie contrainte de mise en page seulement quand vous savez qu'elle s'applique.

Ajouter des commentaires de traducteur dans SwiftUI

Apple documente le paramètre comment: sur Text comme un moyen d'inclure des indices de traduction. Quand l'initialiseur de chaîne pratique d'un contrôle ne fournit pas le commentaire dont vous avez besoin, utilisez son constructeur de contenu avec une vue Text explicite. Apple démontre ce motif pour Label et explique que de nombreux contrôles SwiftUI le prennent en charge. Préparer les vues pour la localisation

L'exemple complet ci-dessous est une petite app macOS SwiftUI. Dans Xcode, créez un projet d'app macOS utilisant SwiftUI, définissez la cible de déploiement sur macOS 13 ou version ultérieure, et remplacez le code généré de l'app et de la vue de contenu par ce fichier unique. Conservez un seul point d'entrée d'app. L'exemple utilise des noms fixes et synthétiques et révèle une phrase de détail quand l'utilisateur clique sur Expand.

import SwiftUI

@main
struct ShapeCommentDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ShapeBrowserView()
        }
    }
}

struct ShapeBrowserView: View {
    @State private var showsDetails = false

    private let shapeName = "Circle A"
    private let collectionName = "Shape Set A"

    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            Text(
                "Round",
                comment: "Category heading above previews of shapes with curved outlines. Adjective describing the shapes."
            )
            .font(.headline)

            Circle()
                .fill(Color.blue)
                .frame(width: 80, height: 80)

            Text(
                "\(shapeName) in \(collectionName)",
                comment: "Caption below a shape preview. The first value is the shape name; the second is the collection containing it. Sample names: Circle A and Shape Set A."
            )

            Button {
                showsDetails = true
            } label: {
                Text(
                    "Expand",
                    comment: "Button below a shape preview that reveals its details beneath the preview. Verb expressing an action."
                )
            }
            .disabled(showsDetails)

            if showsDetails {
                Text(
                    "A shape with a curved outline.",
                    comment: "Detail sentence revealed below the preview after clicking Expand. Describes the displayed circle."
                )
            }
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 300)
    }
}

Cet exemple a été inspecté par rapport aux motifs d'API documentés ; il n'a pas été compilé ni exécuté ici car l'environnement disponible n'a pas de chaîne d'outils Swift.

Pour les chaînes destinées aux utilisateurs créées en dehors d'une vue SwiftUI, Apple documente String(localized:comment:). Utilisez l'argument de commentaire de l'API de localisation pour attacher le contexte au message. Apple prend également en charge une clé de recherche distincte et une valeur source par défaut quand celles-ci doivent différer. Préparer le texte de votre app pour la traduction

Expliquer les valeurs insérées par leur sens et leur relation

La légende dans l'exemple contient deux interpolations Swift : \(shapeName) et \(collectionName). L'interpolation Swift insère les valeurs d'expressions dans un littéral de chaîne. Les noms de variables appartiennent au code source ; l'explication doit rester compréhensible pour quelqu'un qui ne peut pas voir ces noms. Chaînes et caractères

Pour les valeurs synthétiques montrées, la légende anglaise se lit Circle A in Shape Set A. Son commentaire explique à la fois l'ordre des valeurs insérées et leur relation : l'une nomme la forme, et l'autre nomme la collection la contenant. Cela donne plus d'informations utiles que de simplement décrire deux arguments de chaîne.

En revoyant un message interpolé, posez trois questions :

  1. Quel type de contenu peut apparaître à chaque position : un nom, un compteur ou un autre type de valeur ?
  2. Comment les valeurs sont-elles liées entre elles ?
  3. Le commentaire reste-t-il exact pour toute valeur que l'app peut fournir ?

Gardez les exemples clairement identifiés comme des échantillons. Ici, Circle A et Shape Set A illustrent les rôles d'arguments. Ils ne définissent pas une traduction requise ni une liste exhaustive de noms possibles.

Les compteurs nécessitent une décision d'implémentation distincte. Si vous ajoutez plus tard une légende telle que 3 shapes, un commentaire peut expliquer ce qui est compté, mais les variantes grammaticales appartiennent au catalogue. Apple documente l'utilisation de Vary by Plural pour les compteurs interpolés, y compris des formes anglaises distinctes telles que 1 item et 2 items. Localiser et varier le texte avec un catalogue de chaînes

Trouver et inspecter les commentaires dans Xcode

Pour connecter les commentaires source au catalogue, suivez le workflow documenté par Apple :

  1. Choisissez Fichier > Nouveau > Fichier depuis le modèle.
  2. Filtrez pour string, sélectionnez Catalogue de chaînes sous Ressource, et créez-le avec le nom par défaut Localizable.
  3. Choisissez Produit > Construire pour extraire les chaînes localisables.
  4. Sélectionnez Localizable.xcstrings dans le navigateur de projet.
  5. Choisissez Éditeur > Assistant, puis sélectionnez une clé pour inspecter sa source à côté du catalogue. Localiser et varier le texte avec un catalogue de chaînes

Vérifiez le commentaire du catalogue par rapport à l'utilisation réelle. Dans l'exemple, Round doit expliquer un titre de catégorie, et Expand doit décrire la révélation de détails. Si une chaîne est manquante, vérifiez que le code utilise une API localisable et que Use Compiler to Extract Swift Strings est activé. Apple identifie ce réglage de construction comme nécessaire pour l'extraction de chaînes Swift basée sur le compilateur. Découvrir les catalogues de chaînes

Apple prend également en charge l'édition du contexte directement dans la colonne des commentaires du catalogue de chaînes. La génération automatique de commentaires a été introduite dans Xcode 26 ; la documentation actuelle décrit le fait de faire un Control-clic sur une clé et de choisir Générer un commentaire. Si cette option n'est pas disponible dans votre configuration, attachez un commentaire dans le code ou entrez-le dans le catalogue. Code-along : Explorer la localisation avec Xcode, Localiser et varier le texte avec un catalogue de chaînes

Revoyez la formulation générée par rapport au comportement de l'interface. Une description qui identifie correctement un bouton peut encore avoir besoin de préciser l'objet ou le résultat. Pour cet exemple, la distinction utile est que Expand révèle une phrase de détail sous l'aperçu.

Décider si deux étiquettes identiques peuvent partager le contexte

Une orthographe anglaise identique n'établit pas un sens identique. Supposons qu'un autre écran utilise Round comme une action qui arrondit une valeur numérique. Combiner cet usage avec le titre de catégorie de forme exigerait une entrée de catalogue pour décrire deux rôles grammaticaux différents.

Apple explique qu'une chaîne localisable a une clé de recherche et appartient à une table ; les clés sont uniques dans leur table. La documentation Swift d'Apple fournit également un moyen pris en charge d'utiliser une clé distincte avec une valeur source par défaut. Utilisez des clés séparées quand les sens nécessitent des traductions indépendantes, même si leurs valeurs d'affichage anglaises correspondent. Découvrir les catalogues de chaînes, Préparer le texte de votre app pour la traduction

Une règle de décision pratique consiste à se demander si un commentaire peut expliquer avec précision chaque utilisation. Si le sens et le rôle UI restent cohérents, un contexte partagé peut être approprié. Si l'explication doit décrire des opérations sans rapport, repensez la structure des clés. Il s'agit d'une inférence de conception issue du modèle clé-et-table d'Apple, et non d'une règle selon laquelle chaque contrôle a besoin de sa propre chaîne.

Avant de remettre une étiquette, lisez son commentaire sans le code source. Il doit permettre au traducteur d'identifier le sens intentionnel, de situer le texte conceptuellement dans l'interface et de comprendre tout contenu inséré. Révisez le commentaire chaque fois que le comportement ou le rôle de l'étiquette change afin que l'explication continue de décrire l'interface que l'utilisateur voit.

Sources