.XCSTRINGS – Apple Strings Catalog (Strings)

Inhalte werden von Phrase Language AI maschinell aus dem Englischen übersetzt.

Dateierweiterungen	.xcstrings
API-Erweiterung	strings_catalog
Importieren	Ja
Exportieren	Ja
Unterstützung für Pluralformen	Ja
Unterstützung für Beschreibungen	Ja
Format-Optionen Diese Optionen können angegeben werden, wenn eine Datei hochgeladen und/oder heruntergeladen wird. Abhängig von der Methode zum hochladen/Herunterladen (API, CLI, Repo-Sync usw.) können diese in Query-Parametern `hochladen`, `Herunterladen` oder in der Konfigurationsdatei `phrase.yml` angegeben werden.	convert_placeholder default_extraction_state locale_code_mapping

Apple Strings Catalog (.xcstrings) ist ein in Xcode 15 eingeführtes Format für die Lokalisierung. Es verbessert die Art und Weise, wie Entwickler lokalisierte Strings verwalten, indem es strukturierte Formate für die Handhabung von Pluralisierung, gerätespezifischen Variationen und mehr unterstützt. Dieses Format entwickelt sich zum empfohlenen Ansatz für die Verwaltung von Lokalisierungen in iOS- und macOS-Anwendungen.

Die Metadatenfelder kommentieren, extractionState und shouldTranslate werden in der erforderlichen Reihenfolge importiert und exportiert, um die Kompatibilität mit Xcode sicherzustellen.

Phrase ordnet während des Importvorgangs auch Xcode-Übersetzungszustände den nächstgelegenen Strings-Entsprechungen zu und konvertiert sie beim exportieren zurück in Xcode-kompatible Werte. Wenn kein spezifisches Mapping zutrifft, wird translated als Standardwert beim exportieren verwendet. Verwenden Sie bei Bedarf die Option Ignore translation state on import, um das State-Mapping zu überspringen.

Codebeispiel

{
  "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"
}

Bei Verwendung der Phrase CLI folgen Dateiexporte der im .phrase.yml-Konfigurationsfile definierten Struktur. Um sicherzustellen, dass mehrere Sprachen während Pull-Vorgängen in eine einzige .XCSTRINGS-Datei exportiert werden:

Geben Sie in der CLI-Konfigurationsdatei nur ein Dateiziel an.
Verwenden Sie den Parameter locale_ids, um alle im Export enthaltenen Sprachen aufzulisten.

Beispiel für .phrase.yml-Konfiguration

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

Gerätevariationen

Apple Strings Catalog unterstützt Gerätevariationen, die je nach verwendetem Apple-Gerät unterschiedliche Übersetzungsinhalte für denselben Key ermöglichen.

Um Gerätevariationen in Phrase Strings zu handhaben, werden für jedes Gerät separate Keys unter Verwendung des Trennzeichens |==| erstellt. Beim Importieren von .XCSTRINGS-Dateien wird der Gerätetyp unter Verwendung dieses Trennzeichens zum Basis-Key-Namen hinzugefügt.

Beispiel

Der Key mit dem Namen %lld Product(s) Ordered für das Gerät applewatch wird als Plural-Key mit dem Namen %lld Product(s) Ordered|==|device.applewatch in Phrase Strings importiert.

Beim exportieren erkennt Phrase Strings die Gerätevariante mithilfe des Trennzeichens und stellt die ursprüngliche verschachtelte Struktur für das Lokalisierungsformat von Apple wieder her.

{
  "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é"
                }
              }
            }
          }
        }
      }
    }
  }
}

Zeichenfolge-Ersetzungen

Apple Strings Catalog unterstützt Zeichenfolge-Ersetzungen, die flexible Platzhalter für dynamischen Content bereitstellen.

Um Zeichenfolge-Ersetzungen in Phrase Strings zu verarbeiten, werden separate Keys unter Verwendung des Trennzeichens |==| erstellt. Beim importieren von .XCSTRINGS-Dateien wird die Ersetzung unter Verwendung dieses Trennzeichens zum Basis-Key-Namen hinzugefügt.

Phrase Strings unterstützt auch das direkte Erstellen von Zeichenfolgen im Projekt. Wenn Ersetzungsstrukturen manuell erstellt werden, müssen ein Basis-Key und ein entsprechender Key für die Zeichenfolge definiert werden, um sicherzustellen, dass beim exportieren das korrekte verschachtelte Format generiert wird.

Ersetzungen erfordern immer ein spezifisches Format für die Benennung von Keys: keyName|==|substitution.[specifier].

Beispiel: Importieren von Ersetzungsstrukturen aus bestehenden .XCSTRINGS-Dateien

Der Key mit dem Namen birdSightingAlert für die BIRDS-Zeichenfolge wird als Plural-Key mit dem Namen birdSightingAlert|==|substitution.BIRDS in Phrase Strings importiert.

Beim exportieren erkennt Phrase Strings die Zeichenfolge mithilfe des Trennzeichens und stellt die ursprüngliche verschachtelte Struktur für das Lokalisierungsformat von Apple wieder her.

"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"
                }
              }
            }
          }
        }
      }
    }
  }

Beispiel: Erstellen von Zeichenfolgen für Zeichenfolgen von Grund auf

Basis-Key

Ein Basis-Key mit dem Namen keyName repräsentiert die Zeichenfolge im Format der obersten Ebene, die den Platzhalter %#@format@ enthält.

Beim exportieren wird dieser Key als primäre stringUnit für den Eintrag geschrieben:
```
"keyName": {
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "translated",
        "value": "%#@format@"
      }
    }
  }
}
```

Zeichenfolge-Key

Eine Zeichenfolge wird als separater Key unter Verwendung des Formats für die Benennung von Zeichenfolgen definiert: keyName|==|substitution.li.

Dieser Key enthält den Text der Zeichenfolge, typischerweise mit Pluralvarianten. Beim exportieren erkennt Phrase Strings die Zeichenfolge mithilfe des Trennzeichens |==|substitution. und stellt die entsprechende verschachtelte Struktur unter dem Basis-Key wieder her:

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

Format-Optionen

Identifikator	convert_placeholder
Typ	Boolean
Upload	Nein
Download	Ja
Standard	false
Beschreibung	Platzhalter werden konvertiert, um den Format-spezifischen Anforderungen zu entsprechen. Beispiel: `$s`→`$@`, `%s`→`%@`

Identifikator	default_extraction_state
Typ	Zeichenfolge
Upload	Nein
Download	Ja
Standard	null
Beschreibung	Definiert den `extractionState`-Wert, der in die Keys in der exportierten Datei geschrieben wird, wenn für den Key noch kein Extraktionsstatus definiert ist. Wenn ein Key bereits einen `extractionState` enthält, bleibt dessen Wert beim exportieren erhalten. Unterstützt:<1> UI-Downloads API CLI (über `.phrase.yml<2>-Konfiguration) und Repo Sync`

Identifikator	locale_code_mapping
Typ	Objekt
Hochladen	Ja
Herunterladen	Ja
Standard	{}
Beschreibung	Ordnet Phrase-Sprachcodes den Sprachcodes zu, die in die .XCSTRINGS-Datei geschrieben werden. Jeder Key ist der Phrase-Sprachcode; jeder Wert ist der in die Datei geschriebene Code, zum Beispiel: { "en": "en-GB", "fr": "fr-FR" } Beim herunterladen schreibt Phrase das Feld `sourceLanguage` und jeden `localizations`-Key, der mit einem Mapping-Key übereinstimmt, auf den zugeordneten Wert um. Codes ohne Mapping bleiben unverändert. Beim hochladen wendet Phrase dasselbe Mapping in umgekehrter Reihenfolge an und konvertiert Datei-Sprachcodes zurück in die entsprechenden Phrase-Sprachcodes, einschließlich `sourceLanguage`. Diese Option betrifft nur die Sprachcodes, die aus der .XCSTRINGS-Datei selbst gelesen und in diese geschrieben werden. Das dateinamenbasierte Sprach-Mapping, das zum Beispiel in Dateibenennungsmustern der Git-Integration verwendet wird, ist eine separate Einstellung, die Dateipfade anstelle der Codes innerhalb von .XCSTRINGS zuordnet.