.XCSTRINGS - Apple Strings Catalog (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 lorsqu'un fichier est charger et/ou Télécharger. Selon la méthode de charger/Télécharger (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 Strings localisées en prenant en charge des format structurés pour gérer la pluralisation, les variations spécifiques à l'appareil, et plus encore. Ce format devient l'approche recommandée pour gérer les localisations dans les application iOS et macOS.

Les champs de métadonnées comment, extractionState et shouldTranslate sont importer et exporter dans la commande requise pour assurer la compatibilité avec Xcode.

Phrase mappe également les états de traduction Xcode aux équivalents Strings les plus proches lors de l'importer et les convertit en valeurs compatibles avec Xcode lors de l'exporter. Si aucun mappage spécifique ne s'applique, translated est utilisé comme valeur d'exporter par défaut. Si nécessaire, utiliser 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 téléchargement :

Spécifier une seule cible de fichier dans le fichier de configuration CLI.
Utiliser le paramètre locale_ids pour lister tous les paramètre linguistique inclus 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 d'appareil

Apple Strings Catalog prend en charge les variations d'appareil, qui permettent des contenus de traduction différents pour la même clé selon l'appareil Apple utilisé.

Pour gérer les variations d'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 clé de base en utilisant 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'exporter, Phrase Strings détecte la variante de l'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": "Indicates the number of products ordered, with device-specific variations",
      "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îne

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

Pour gérer les substitutions de chaîne 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'exporter.

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'exporter, 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'exporter, cette clé est écrite comme la 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'exporter, Phrase Strings détecte la substitution en utilisant le 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
Charger	non
Télécharger	Oui
Par défaut	null
Description	Définit la valeur `extractionState` écrite sur les clés dans le fichier exporter 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 préservée lors de l'exporter. Pris en charge : téléchargement de 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 paramètre linguistique Phrase aux codes de paramètre linguistique écrits dans le fichier .XCSTRINGS. Chaque clé est le code de paramètre linguistique Phrase ; chaque valeur est le code écrit dans le fichier, par exemple : { "en": "en-GB", \"fr\": \"fr-FR\" } Lors du téléchargement, Phrase réécrit le champ `sourceLanguage` et toute clé `localizations` qui correspond à une clé de mappage vers la valeur mappée. Les codes sans mappage restent inchangés. Lors du charger, Phrase applique le même mappage en sens inverse et reconvertit les codes de paramètre linguistique de fichier en codes de paramètre linguistique Phrase correspondants, y compris `sourceLanguage`. Cette option affecte uniquement les codes de paramètre linguistique lus et écrits dans le fichier .XCSTRINGS lui-même. Le mappage de paramètre linguistique 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.