.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 Herunterladen wird. Abhängig von der hochladen/Herunterladen-Methode (API, CLI, Repo-Sync usw.) können diese in Query-Parametern `hochladen`, `Herunterladen` oder in der `phrase.yml` Konfigurationsdatei angegeben werden.	convert_placeholder default_extraction_state locale_code_mapping

Apple Strings Catalog (.xcstrings) ist ein Lokalisierungs-Format, das in Xcode 15 eingeführt wurde. Es verbessert die Art und Weise, wie Entwickler lokalisierte Strings verwalten, indem es strukturierte Format für die Handhabung von Pluralisierung, gerätespezifischen Variationen und mehr unterstützt. Dieses Format wird 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 importieren und exportieren, um die Kompatibilität mit Xcode sicherzustellen.

Phrase ordnet Xcode-Übersetzungszustände während des importieren auch den nächstgelegenen Strings-Äquivalenten zu und konvertiert sie beim exportieren zurück in Xcode-kompatible Werte. Wenn kein spezifisches Mapping zutrifft, wird translated als Standard-exportieren-Wert 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 Datei-exportieren der im .phrase.yml Konfigurationsdatei definierten Struktur. Um sicherzustellen, dass mehrere Sprachen während Pull-Vorgängen in eine einzige .XCSTRINGS-Datei exportiert werden:

Geben Sie nur ein Zielsprache-File in der CLI-Konfigurationsdatei an.
Verwenden Sie den Parameter locale_ids, um alle im exportieren enthaltenen Sprache-Locales aufzulisten.

Beispiel .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 unterschiedliche Übersetzungsinhalte für denselben Key ermöglichen, abhängig vom verwendeten Apple-Gerät.

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 applewatch-Gerät wird als Plural-Key mit dem Namen %lld Product(s) Ordered|==|device.applewatch in Phrase Strings importieren.

Während des exportieren erkennt Phrase Strings die Gerätevariante mithilfe des Trennzeichens und stellt die ursprüngliche verschachtelte Struktur für das Lokalisierungs-Format 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 handhaben, werden separate Keys mithilfe 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 Ersetzungs-Key definiert werden, um sicherzustellen, dass beim exportieren das korrekte verschachtelte Format generiert wird.

Ersetzungen erfordern immer ein spezifisches Key-Benennungs-Format: 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.

Während des exportieren erkennt Phrase Strings die Zeichenfolge mithilfe des Trennzeichens und stellt die ursprüngliche verschachtelte Struktur für das Lokalisierungs-Format 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 Zeichenfolge-Format-Formats definiert: keyName|==|substitution.li.

Dieser Key enthält den Zeichenfolge-Content, typischerweise mit Pluralvariationen. Während des exportieren erkennt Phrase Strings die Zeichenfolge mithilfe des |==|substitution.-Trennzeichens 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 Match-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: 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-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 jede `localizations`-Key, die 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 Git-Integration-Dateibenennungsmustern verwendet wird, ist eine separate Einstellung, die Dateipfade anstelle der Codes innerhalb von .XCSTRINGS zuordnet.