.XCSTRINGS - Catalogue de chaînes Apple (Strings)

Le contenu est traduit de l’anglais par Phrase Language AI.

Extensions de fichier	.xcstrings
Extension d'API	strings_catalog
Import	oui
Export	oui
Prise en charge des formes plurielles	oui
Prise en charge de la description	oui
Options de format Ces options peuvent être spécifiées lors du téléversement et/ou du téléchargement d’un fichier. Selon la méthode de téléversement ou de téléchargement (API, CLI, synchronisation de dépôt, etc.), elles peuvent être spécifiées dans les paramètres de requête `Upload`, `Download` ou dans le fichier de configuration `phrase.yml`.	convert_placeholder default_extraction_state locale_code_mapping

Apple Strings Catalog (.xcstrings) est un format de localisation introduit dans Xcode 15. Il améliore la façon dont les développeurs gèrent les chaînes localisées en prenant en charge des formats structurés pour gérer la pluralisation, les variations spécifiques aux appareils, et plus encore. Ce format devient l'approche recommandée pour gérer les localisations dans les applications iOS et macOS.

Les champs de métadonnées comment, extractionState et shouldTranslate sont importés et exportés dans l'ordre requis pour assurer la compatibilité avec Xcode.

Phrase mappe également les états de traduction Xcode vers les équivalents Strings les plus proches lors de l'importation et les convertit en valeurs compatibles avec Xcode lors de l'exportation. Si aucune correspondance spécifique ne s'applique, translated est utilisé comme valeur d'exportation par défaut. Si nécessaire, utilisez l'option Ignore translation state on import pour ignorer le mappage d'état.

Exemple de code

{
  "sourceLanguage": "en",
  "strings": {
    "Sync Warning": {
      "comment": "Sync function unavailable message",
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Cloud Sync must be enabled to use this feature."
          }
        },
        "fr": {
          "stringUnit": {
            "state": "translated",
            "value": "La synchronisation cloud doit être activée pour utiliser cette fonction."
          }
        }
      }
    },
    "Chosen Collections": {
      "comment": "View title indicating selected photo collections",
      "localizations": {
        "fr": {
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld collection sélectionnée"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld collections sélectionnées"
                }
              }
            }
          }
        },
        "en": {
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld Collection Selected"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld Collections Selected"
                }
              }
            }
          }
        }
      }
    },
    "Settings Hub": {
      "localizations": {
        "es": {
          "stringUnit": {
            "state": "translated",
            "value": "Centro de configuración"
          }
        }
      }
    }
  },
  "version": 1.0
}

Lors de l'utilisation de Phrase CLI, les exportations de fichiers suivent la structure définie dans le fichier de configuration .phrase.yml. Pour garantir que plusieurs langues sont exportées dans un seul fichier .XCSTRINGS lors des opérations de pull :

Spécifiez une seule cible de fichier dans le fichier de configuration CLI.
Utilisez le paramètre locale_ids pour lister toutes les locales de langue incluses dans l'exportation.

Exemple de configuration .phrase.yml

pull:
  targets:
    - file: ./i18n-test/Localizable.xcstrings
      params:
        locale_id: en # Main language for the download
        locale_ids: # Additional languages to include
          - de
          - es
          - fr 
        file_format: strings_catalog

Variations par appareil

Le catalogue de chaînes Apple prend en charge les variations par appareil, qui permettent des contenus de traduction différents pour la même clé selon l'appareil Apple utilisé.

Pour gérer les variations par appareil dans Phrase Strings, des clés distinctes sont créées pour chaque appareil en utilisant le séparateur |==|. Lors de l'importation de fichiers .XCSTRINGS, le type d'appareil est ajouté au nom de la clé de base à l'aide de ce séparateur.

Exemple

La clé nommée %lld Product(s) Ordered pour l'appareil applewatch est importée en tant que clé plurielle nommée %lld Product(s) Ordered|==|device.applewatch dans Phrase Strings.

Lors de l'exportation, Phrase Strings détecte la variante d'appareil à l'aide du séparateur et restaure sa structure imbriquée d'origine pour le format de localisation d'Apple.

{
  "sourceLanguage": "en",
  "strings": {
    "%lld Product(s) Ordered": {
      "comment": « Indique le nombre de produits commandés, avec des variations spécifiques à l'appareil »
      "localizations": {
        "en": {
          "variations": {
            "device": {
              "applewatch": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (Apple Watch)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (Apple Watch)"
                      }
                    }
                  }
                }
              },
              "ipad": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (iPad)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (iPad)"
                      }
                    }
                  }
                }
              },
              "iphone": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (iPhone)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (iPhone)"
                      }
                    }
                  }
                }
              },
              "mac": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (Mac)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (Mac)"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "fr": {
          "variations": {
            "plural": {
              "few": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produit(s) commandé(s)"
                }
              },
              "many": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produits commandés"
                }
              },
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produit commandé"
                }
              }
            }
          }
        }
      }
    }
  }
}

Substitutions de chaînes

Apple Strings Catalog prend en charge les substitutions de chaînes qui fournissent des espaces réservés flexibles pour le contenu dynamique.

Pour gérer les substitutions de chaînes dans Phrase Strings, des clés distinctes sont créées à l'aide du séparateur |==|. Lors de l'importation de fichiers .XCSTRINGS, la substitution est ajoutée au nom de la clé de base à l'aide de ce séparateur.

Phrase Strings prend également en charge la création de chaînes de substitution directement dans le projet. Lorsque des structures de substitution sont créées manuellement, une clé de base et une clé de substitution correspondante doivent être définies pour garantir que le format imbriqué correct est généré lors de l'exportation.

Les substitutions nécessitent toujours un format de nommage de clé spécifique : keyName|==|substitution.[specifier].

Exemple : Importation de structures de substitution à partir de fichiers .XCSTRINGS existants

La clé nommée birdSightingAlert pour la substitution BIRDS est importée en tant que clé plurielle nommée birdSightingAlert|==|substitution.BIRDS dans Phrase Strings.

Lors de l'exportation, Phrase Strings détecte la substitution à l'aide du séparateur et restaure sa structure imbriquée d'origine pour le format de localisation d'Apple.

"birdSightingAlert": {
  "comment": "Alert message indicating the number of birds spotted",
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "new",
        "value": "You spotted %#@BIRDS@!"
      },
      "substitutions": {
        "BIRDS": {
          "formatSpecifier": "BIRDS",
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "new",
                  "value": "a bird"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "new",
                  "value": "several birds"
                }
              },
              "zero": {
                "stringUnit": {
                  "state": "new",
                  "value": "no birds"
                }
              }
            }
          }
        }
      }
    }
  }

Exemple : Création de chaînes de substitution à partir de zéro

Clé de base

Une clé de base nommée keyName représente la chaîne de format de niveau supérieur qui contient l'espace réservé de substitution %#@format@.

Lors de l'exportation, cette clé est écrite en tant que stringUnit principale pour l'entrée :
```
"keyName": {
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "translated",
        "value": "%#@format@"
      }
    }
  }
}
```

Clé de substitution

Une chaîne de substitution est définie comme une clé distincte utilisant le format de nommage de substitution : keyName|==|substitution.li.

Cette clé contient le texte de substitution, généralement avec des variantes plurielles. Lors de l'exportation, Phrase Strings détecte la substitution à l'aide du séparateur |==|substitution. et restaure la structure imbriquée correspondante sous la clé de base :

{
  "sourceLanguage": "en",
  "strings": {
    "keyName": {
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "%#@format@"
          },
          "substitutions": {
            "li": {
              "formatSpecifier": "li",
              "variations": {
                "plural": {
                  "one": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ day"
                    }
                  },
                  "other": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ days"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "version": 1.0
}

Options de format

Identifiant	convert_placeholder
Type	booléen
Charger	non
Télécharger	Oui
Par défaut	false
Description	L'espace réservé sera converti pour correspondre aux exigences spécifiques du format. Exemple : `$s`→`$@`, `%s`→`%@`

Identifiant	default_extraction_state
Type	chaîne
Chargement	non
Télécharger	Oui
Par défaut	null
Description	Définit la valeur `extractionState` écrite dans les clés du fichier exporté lorsqu'aucun état d'extraction n'est déjà défini sur la clé. Si une clé contient déjà un `extractionState`, sa valeur est conservée lors de l'exportation. Pris en charge : Téléchargements via l'interface utilisateur API CLI (via la configuration `.phrase.yml`) et Repo Sync

Identifiant	locale_code_mapping
Type	objet
Chargement	oui
Téléchargement	Oui
Par défaut	}
Description	Associe les codes de langue Phrase aux codes de langue écrits dans le fichier .XCSTRINGS. Chaque clé est le code de langue Phrase ; chaque valeur est le code écrit dans le fichier, par exemple : { "en": "en-GB", "fr": "fr-FR" } Au téléchargement, Phrase réécrit le champ `sourceLanguage` et toute clé de `localizations` qui correspond à une clé de mappage vers la valeur mappée. Les codes sans mappage restent inchangés. Lors du chargement, Phrase applique le même mappage en sens inverse et convertit les codes de langue du fichier en codes de langue Phrase correspondants, y compris `sourceLanguage`. Cette option affecte uniquement les codes de langue lus et écrits dans le fichier .XCSTRINGS lui-même. Le mappage de langue basé sur le nom de fichier, utilisé par exemple dans les modèles de nommage de fichiers d'intégration Git, est un paramètre distinct qui mappe les chemins de fichiers plutôt que les codes à l'intérieur de .XCSTRINGS.

Migration d'iOS Strings (.strings) vers Strings Catalog (.xcstrings)

L'ancien format iOS Strings (.strings) traite une séquence littérale antislash-n (\\n) dans le contenu de la traduction comme équivalente à un vrai saut de ligne. Par conséquent, les traductions créées ou modifiées lors de l'utilisation du format .strings peuvent contenir le texte littéral \\n au lieu d'un caractère de saut de ligne réel.

Le format Strings Catalog (.xcstrings) est basé sur JSON. Lorsqu'un contenu contenant une séquence littérale \\n est exporté vers .xcstrings, l'encodage JSON échappe ce texte littéral en \\\\n dans le fichier. Ce comportement n'est pas une erreur de double échappement. Il reflète le texte littéral \\n déjà présent dans le contenu de la traduction, exporté en utilisant l'échappement JSON correct.

Pour résoudre ce problème après la migration de .strings vers .xcstrings, remplacez les séquences littérales \\n dans le contenu concerné par de vrais sauts de ligne :

Exportez le contenu comme d'habitude.
Ouvrez le fichier exporté dans un éditeur de texte.
Remplacez toutes les occurrences de la séquence littérale \\n par un vrai saut de ligne.
Réimportez le fichier.

La fonction de recherche et remplacement intégrée à l’application ne prend pas en charge l’insertion d’un vrai saut de ligne, ce remplacement devant être effectué dans un éditeur de texte externe avant de réimporter le fichier.