.XCSTRINGS - Apple Strings Catalog (Strings)

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

Extensions de fichiers	.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échargement et/ou de l'importation d'un fichier. Selon la méthode de téléchargement/importation (API, CLI, synchronisation de dépôt, etc.), elles peuvent être spécifiées dans les paramètres de requête `Charger`, `Télécharger` ou dans le fichier de configuration `phrase.yml`.	convert_placeholder default_extraction_state

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 garantir la compatibilité avec Xcode.

Phrase associe également les états de traduction Xcode aux équivalents Strings les plus proches lors de l'importation et les convertit en valeurs compatibles avec Xcode lors de l'exportation. Si aucun mappage spécifique ne s'applique, traduit est utilisé comme valeur d'exportation par défaut. Si nécessaire, utilisez l'option Ignorer l'état de traduction à l'importation 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 tirage :

Spécifiez uniquement une cible de fichier dans le fichier de configuration CLI.
Utilisez le paramètre locale_ids pour lister tous les paramètres linguistiques 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, ce qui permet différents contenus de traduction pour la même clé en fonction de l'appareil Apple utilisé.

Pour gérer les variations d'appareil dans Phrase Strings, des clés séparées 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 en utilisant ce séparateur.

Exemple

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

Lors de l'exportation, 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": "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

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

Pour gérer les substitutions de chaînes dans Phrase Strings, des clés séparées 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 comme l'unité de chaîne principale stringUnit 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é séparée utilisant le format de nommage de substitution : keyName|==|substitution.li.

Cette clé contient le texte de substitution, généralement avec des variations plurielles. Lors de l'exportation, 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": "%@ jour"
                    }
                  },
                  "other": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ jours"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "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	nul
Description	Définit la valeur `extractionState` écrite dans les clés du fichier exporté lorsque 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'exportation. Pris en charge dans : Téléchargements de l'interface utilisateur API CLI (via la configuration `.phrase.yml`) et synchronisation de dépôt