.XCSTRINGS – Apple Strings Catalog (Strings)

Obsah je strojově přeložen z angličtiny s použitím Phrase Language AI.

Přípony souborů	.xcstrings
API rozšíření	strings_catalog
Import	Ano
Export	Ano
Podpora plurálových tvarů	Ano
Podpora pro popis	Ano
Možnosti formátu Tyto možnosti lze specifikovat při nahrání a/nebo Stáhnout souboru. V závislosti na metodě nahrát/Stáhnout (API, CLI, Repo sync atd.) mohou být specifikovány v dotaz parametrech `Upload`, `Download` nebo v konfiguračním souboru `phrase.yml`.	convert_placeholder default_extraction_state locale_code_mapping

Apple Strings Catalog (.xcstrings) je formát lokalizace představený v Xcode 15. Vylepšuje způsob, jakým vývojáři spravují lokalizované Strings, podporou strukturovaných formátů pro zpracování plurálu, variací specifických pro zařízení a dalších. Tento formát se stává doporučeným přístupem pro správu lokalizací v aplikacích pro iOS a macOS.

Pole metadat komentář, extractionState a shouldTranslate jsou importována a stáhnout v požadovaném objednávka pro zajištění kompatibility s Xcode.

Phrase také mapuje stavy překladu Xcode na nejbližší ekvivalenty Strings během import a převádí je zpět na hodnoty kompatibilní s Xcode při stáhnout. Pokud se nepoužije žádné konkrétní mapování, jako výchozí hodnota pro stáhnout se použije translated. V případě potřeby použijte možnost Ignore translation state on import pro přeskočení mapování stavu.

Vzor kódu

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

Při použití Phrase CLI následuje export souborů strukturu definovanou v konfiguračním souboru .phrase.yml. Pro zajištění exportu více jazyků do jednoho souboru .XCSTRINGS během operací pull:

V konfiguračním souboru CLI zadejte pouze jeden cíl souboru.
Použijte parametr locale_ids k vypsání všech kódů jazyka zahrnutých v exportu.

Příklad konfigurace .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

Variace zařízení

Apple Strings Catalog podporuje variace zařízení, které umožňují různý obsah překladu pro stejný klíč v závislosti na používaném zařízení Apple.

Pro zpracování variací zařízení v Phrase Strings jsou pro každé zařízení vytvořeny samostatné klíče pomocí oddělovače |==|. Při importu souborů .XCSTRINGS je typ zařízení přidán k názvu základního klíče pomocí tohoto oddělovače.

Příklad

Klíč s názvem %lld Product(s) Ordered pro zařízení applewatch je importován jako plurální klíč s názvem %lld Product(s) Ordered|==|device.applewatch do Phrase Strings.

Během stáhnout, Phrase Strings detekuje variantu zařízení pomocí oddělovače a obnoví jeho původní vnořenou strukturu pro Apple Strings Catalog formát.

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

Nahrazení řetězec

Apple Strings Catalog podporuje nahrazení řetězec, které poskytují flexibilní zástupný znak pro dynamický obsah.

Pro zpracování nahrazení řetězec v Phrase Strings jsou vytvořeny samostatné klíč pomocí oddělovače |==|. Při importu souborů .XCSTRINGS je nahrazení přidáno k názvu základní klíč pomocí tohoto oddělovače.

Phrase Strings také podporuje vytváření řetězec přímo v projekt. Když jsou struktury nahrazení vytvořeny ručně, musí být definován základní klíč a odpovídající klíč, aby bylo zajištěno, že během stáhnout bude vygenerován správný vnořený formát.

Nahrazení vždy vyžadují specifický formát pojmenování klíč: keyName|==|substitution.[specifier].

Příklad: Import struktur nahrazení z existujících souborů .XCSTRINGS

Klíč s názvem birdSightingAlert pro BIRDS řetězec je importován jako množný klíč s názvem birdSightingAlert|==|substitution.BIRDS do Phrase Strings.

Během stáhnout, Phrase Strings detekuje řetězec pomocí oddělovače a obnoví jeho původní vnořenou strukturu pro Apple Strings Catalog formát.

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

Příklad: Vytváření řetězců od nuly

Základní klíč

Základní klíč s názvem keyName představuje formát řetězec nejvyšší úrovně, který obsahuje zástupný znak %#@format@.

Při stáhnout je tento klíč zapsán jako primární stringUnit pro položka:
```
"keyName": {
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "translated",
        "value": "%#@format@"
      }
    }
  }
}
```

Klíč řetězec

Řetězec je definován jako samostatný klíč pomocí formát pojmenování řetězec: keyName|==|substitution.li.

Tento klíč obsahuje text řetězec, obvykle s množnými variantami. Během exportu Phrase Strings detekuje nahrazení pomocí oddělovače |==|substitution. a obnoví odpovídající vnořenou strukturu pod základním klíčem:

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

Možnosti formátu

Identifikátor	convert_placeholder
Typ	boolean
Nahrát	Ne
Stáhnout	Ano
Výchozí	false
Popis	Zástupný znak bude převeden tak, aby odpovídal specifickým požadavkům na formát. Příklad: `$s`→`$@`, `%s`→`%@`

Identifikátor	default_extraction_state
Typ	řetěz\|ec
Nahrát	Ne
Stáhnout	Ano
Výchozí	null
Popis	Definuje hodnotu `extractionState` zapsanou ke klíčům v exportovaném souboru, pokud u klíče není již definován žádný stav extrakce. Pokud klíč již obsahuje `extractionState`, jeho hodnota je během exportu zachována. Podporováno: Stahování přes UI API CLI (přes konfiguraci `.phrase.yml`) a Repo Sync

Identifikátor	locale_code_mapping
Typ	objekt
Nahrání	Ano
Stažení	Ano
Výchozí	{}
Popis	Mapuje kódy jazyka Phrase na kódy jazyka zapsané do souboru .XCSTRINGS. Každý klíč je kód jazyka Phrase; každá hodnota je kód zapsaný do souboru, například: { "en": "en-GB", "fr": "fr-FR" } Při stahování Phrase přepíše pole `sourceLanguage` a jakýkoli klíč `localizations`, který odpovídá mapovacímu klíči, na mapovanou hodnotu. Kódy bez mapování zůstávají nezměněny. Při nahrávání Phrase aplikuje stejné mapování v opačném pořadí a převede kódy jazyka souboru zpět na odpovídající kódy jazyka Phrase, včetně `sourceLanguage`. Tato volba ovlivňuje pouze kódy jazyka čtené ze souboru .XCSTRINGS a zapisované do něj. Mapování kódů jazyka založené na názvech souborů, používané například ve vzorech pojmenování souborů pro integrace Git, je samostatné nastavení, které mapuje cesty k souborům, nikoli kódy uvnitř .XCSTRINGS.