.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 sie 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 zu gewährleisten.

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. Falls erforderlich, kann die Option Ignore translation state on import genutzt werden, 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.0
}

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

In der CLI-Konfigurationsdatei sollte nur ein Dateiziel angegeben werden.
Mit dem Parameter locale_ids werden alle im Export enthaltenen Sprach-Locales aufgelistet.

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 Gerät applewatch wird als Plural-Schlüssel namens %lld Product(s) Ordered|==|device.applewatch in Phrase Strings importiert.

Beim Export 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 die Anzahl der bestellten Produkte an, mit gerätespezifischen 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é"
                }
              }
            }
          }
        }
      }
    }
  }
}

String-Substitutionen

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 Substitutions-Strings im Projekt. Wenn Substitutionsstrukturen manuell erstellt werden, müssen ein Basis-Schlüssel und ein entsprechender Substitutions-Schlüssel definiert werden, um sicherzustellen, dass beim Export das korrekte verschachtelte Format generiert wird.

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

Beispiel Importieren von Substitutionsstrukturen aus vorhandenen .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.

Beim Export 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 Substitutions-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 Export wird dieser Schlüssel als primäre stringUnit für den Eintrag geschrieben:
```
"keyName": {
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "translated",
        "value": "%#@format@"
      }
    }
  }
}
```

Substitutionsschlüssel

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

Dieser Schlüssel enthält den Substitutionstext, typischerweise mit Pluralvarianten. 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.0
}

Format-Optionen

Identifikator	convert_placeholder
Typ	Boolean
Upload	Nein
Download	Ja
Standard	false
Beschreibung	Platzhalter werden konvertiert, 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-Gebietsschema-Code; jeder Wert ist der Code, der in die Datei geschrieben wird, 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 Zuordnung bleiben unverändert. Beim Upload wendet Phrase dasselbe Mapping in umgekehrter Richtung an und konvertiert Datei-Gebietsschema-Codes zurück in die entsprechenden Phrase-Gebietsschema-Codes, einschließlich `sourceLanguage`. Diese Option betrifft nur die Gebietsschema-Codes, die aus der .XCSTRINGS-Datei selbst gelesen und in diese geschrieben werden. Das dateinamenbasierte Gebietsschema-Mapping, das beispielsweise in Git-Integrations-Dateibenennungsmustern 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 literale 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 literalen Text \n anstelle eines tatsächlichen Zeilenumbruchzeichens enthalten.

Strings Catalog (.xcstrings) ist ein JSON-basiertes Format. Wenn Inhalte, die eine literale \n-Sequenz enthalten, in .xcstrings exportiert werden, maskiert die JSON-Kodierung diesen literalen Text als \\n in der Datei. Dieses Verhalten ist kein Fehler durch doppelte Maskierung. Es spiegelt den literalen \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, müssen die literalen \n-Sequenzen im betroffenen Inhalt durch echte Zeilenumbrüche ersetzt werden:

Der Inhalt wird wie gewohnt exportiert.
Die exportierte Datei sollte in einem Texteditor geöffnet werden.
Alle Vorkommen der literalen \n-Sequenz sollten durch einen echten Zeilenumbruch ersetzt werden.
Die Datei sollte erneut importiert werden.

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