.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 beim Hoch- und/oder Herunterladen einer Datei angegeben werden. Je nach Upload-/Download-Methode (API, CLI, Repo-Sync usw.) können diese in Abfrageparametern `Upload`, `Download` oder in der Konfigurationsdatei `phrase.yml` angegeben werden.	convert_placeholder default_extraction_state locale_code_mapping

Apple Strings Catalog (.xcstrings) ist ein mit Xcode 15 eingeführtes Lokalisierungsformat. 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 comment, extractionState und shouldTranslate werden in der erforderlichen Reihenfolge importiert und exportiert, um die Kompatibilität mit Xcode sicherzustellen.

Phrase ordnet beim Import zudem Xcode-Übersetzungsstatus den entsprechenden Strings-Äquivalenten zu und konvertiert sie beim Export zurück in Xcode-kompatible Werte. Wenn keine spezifische Zuordnung zutrifft, wird translated als Standard-Exportwert verwendet. Bei Bedarf wird die Option Ignore translation state on import genutzt, um die Statuszuordnung 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
}

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

In der CLI-Konfigurationsdatei sollte nur ein Dateiziel angegeben werden.
Der Parameter locale_ids listet alle im Export enthaltenen Sprach-Locales auf.

Beispiel für eine .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 Schlüssel ermöglichen.

Um Gerätevariationen in Phrase Strings zu handhaben, werden für jedes Gerät separate Schlüssel unter Verwendung des Trennzeichens |==| erstellt. Beim Importieren von .XCSTRINGS-Dateien wird der Gerätetyp unter Verwendung dieses Trennzeichens an den Basis-Schlüsselnamen angehängt.

Beispiel

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

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

{
  "sourceLanguage": "en",
  "strings": {
    "%lld Product(s) Ordered": {
      "comment": Gibt an, wie viele Produkte bestellt wurden, inklusive gerätespezifischer Varianten,
      "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é"
                }
              }
            }
          }
        }
      }
    }
  }
}

Ersetzungen

Apple Strings Catalog unterstützt String-Substitutionen, die flexible Platzhalter für dynamische Inhalte bereitstellen.

Um String-Substitutionen in Phrase Strings zu handhaben, werden separate Schlüssel unter Verwendung des Trennzeichens |==| erstellt. Beim Importieren von .XCSTRINGS-Dateien wird die Substitution unter Verwendung dieses Trennzeichens an den Basis-Schlüsselnamen angehängt.

Phrase Strings unterstützt auch das direkte Erstellen von Ersetzungs-Strings im Projekt. Wenn Substitutionsstrukturen manuell erstellt werden, müssen ein Basis-Schlüssel und ein entsprechender Substitutionsschlüssel definiert werden, um sicherzustellen, dass beim Export das korrekte verschachtelte Format generiert wird.

Substitutionen erfordern immer ein spezifisches Schlüsselbenennungsformat: keyName|==|substitution.[specifier].

Beispiel: Importieren von Ersetzungsstrukturen aus bestehenden .XCSTRINGS-Dateien

Der Schlüssel namens birdSightingAlert für die BIRDS-Substitution wird als Plural-Schlüssel namens birdSightingAlert|==|substitution.BIRDS in Phrase Strings importiert.

Während des Exports erkennt Phrase Strings die Substitution mithilfe des Trennzeichens und stellt ihre 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 Ersetzungs-Strings von Grund auf

Basis-Schlüssel

Ein Basis-Schlüssel namens keyName repräsentiert den Format-String auf oberster Ebene, der den Substitutions-Platzhalter %#@format@ enthält.

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

Ersetzungsschlüssel

Ein Ersetzungs-String wird als separater Schlüssel unter Verwendung des Ersetzungs-Benennungsformats definiert: keyName|==|substitution.li.

Dieser Schlüssel enthält den Ersetzungstext, typischerweise mit Pluralformen. Während des Exports erkennt Phrase Strings die Ersetzung mithilfe des Trennzeichens |==|substitution. und stellt die entsprechende verschachtelte Struktur unter dem Basisschlüssel wieder her:

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

Format-Optionen

Identifikator	convert_placeholder
Typ	Boolean
Upload	Nein
Download	Ja
Standard	false
Beschreibung	Der Platzhalter wird umgewandelt, um den formatspezifischen Anforderungen zu entsprechen. Beispiel: `$s`→`$@`, `%s`→`%@`

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

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

Migration von iOS Strings (.strings) zu Strings Catalog (.xcstrings)

Das ältere iOS-Strings-Format (.strings) behandelt eine wörtliche Backslash-n-Sequenz (\\n) im Übersetzungsinhalt als äquivalent zu einem echten Zeilenumbruch. Infolgedessen können Übersetzungen, die während der Verwendung des .strings-Formats erstellt oder bearbeitet wurden, den wörtlichen Text \n anstelle eines tatsächlichen Zeilenumbruchzeichens enthalten.

Strings Catalog (.xcstrings) ist ein JSON-basiertes Format. Wenn Inhalte, die eine wörtliche \n-Sequenz enthalten, in .xcstrings exportiert werden, maskiert die JSON-Kodierung diesen wörtlichen Text als \n in der Datei. Dieses Verhalten ist kein Fehler durch doppelte Maskierung. Es spiegelt den wörtlichen \n-Text wider, der bereits im Übersetzungsinhalt vorhanden ist und unter Verwendung der korrekten JSON-Maskierung exportiert wurde.

Um dies nach der Migration von .strings zu .xcstrings zu beheben, sollten die wörtlichen \n-Sequenzen im betroffenen Inhalt durch echte Zeilenumbrüche ersetzt werden:

Exportiere den Inhalt wie gewohnt.
Öffne die exportierte Datei in einem Texteditor.
Ersetze alle Vorkommen der wörtlichen \n-Sequenz durch einen echten Zeilenumbruch.
Importiere die Datei erneut.

Da die In-App-Suche und -Ersetzung das Einfügen eines echten Zeilenumbruchs nicht unterstützt, muss diese Ersetzung in einem externen Texteditor vorgenommen werden, bevor die Datei erneut importiert wird.