.XCSTRINGS – Katalog řetězců Apple (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ávání a/nebo stahování souboru. V závislosti na metodě nahrávání/stahování (API, CLI, synchronizace repozitáře atd.) lze tyto možnosti specifikovat v parametrech dotazu `Nahrát`, `Stáhnout` nebo v konfiguračním souboru `phrase.yml`.	convert_placeholder default_extraction_state locale_code_mapping

Katalog řetězců Apple (.xcstrings) je lokalizační formát představený v Xcode 15. Vylepšuje způsob, jakým vývojáři spravují lokalizované řetězce, díky podpoře 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.

Metadata pole comment, extractionState a shouldTranslate jsou importována a exportována v požadovaném pořadí, aby byla zajištěna kompatibilita s Xcode.

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

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 se exporty souborů řídí strukturou 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 jazykových lokalizací 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í

Katalog řetězců Apple 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 se pro každé zařízení vytvoří samostatné klíče pomocí oddělovače |==|. Při importu souborů .XCSTRINGS se typ zařízení přidává 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 množný klíč s názvem %lld Product(s) Ordered|==|device.applewatch do Phrase Strings.

Během exportu Phrase Strings detekuje variantu zařízení pomocí oddělovače a obnoví její původní vnořenou strukturu pro lokalizační formát společnosti Apple.

{
  "sourceLanguage": "en",
  "strings": {
    "%lld Product(s) Ordered": {
      "comment": Uvádí počet objednaných produktů s variantami specifickými pro zařízení.
      "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é"
                }
              }
            }
          }
        }
      }
    }
  }
}

Substituce řetězců

Apple Strings Catalog podporuje substituce řetězců, které poskytují flexibilní zástupné symboly pro dynamický obsah.

Pro zpracování substitucí řetězců ve Phrase Strings se vytvářejí samostatné klíče pomocí oddělovače |==|. Při importu souborů .XCSTRINGS se substituce přidává k názvu základního klíče pomocí tohoto oddělovače.

Phrase Strings také podporuje vytváření substitučních řetězců přímo v projektu. Při ručním vytváření struktur substitucí musí být definován základní klíč a odpovídající substituční klíč, aby byl při exportu zajištěn správný vnořený formát.

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

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

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

Během exportu Phrase Strings detekuje substituci pomocí oddělovače a obnoví její původní vnořenou strukturu pro lokalizační formát společnosti Apple.

"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í substitučních řetězců od nuly

Základní klíč

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

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

Klíč substituce

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

Tento klíč obsahuje substituční text, obvykle s variantami množného čísla. Během exportu Phrase Strings detekuje substituci 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ý symbol bude převeden tak, aby odpovídal specifickým požadavkům formátu. Příklad: `$s`→`$@`, `%s`→`%@`

Identifikátor	default_extraction_state
Typ	řetěz\|ec
Nahrání	Ne
Stáhnout	Ano
Výchozí	null
Popis	Definuje hodnotu `extractionState` zapsanou ke klíčům v exportovaném souboru, pokud u klíče ještě není definován žádný stav extrakce. Pokud klíč již obsahuje `extractionState`, jeho hodnota je během exportu zachována. Podporováno: Stahování z uživatelského rozhraní 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 národního prostředí Phrase na kódy národního prostředí zapsané do souboru .XCSTRINGS. Každý klíč je kód lokality 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í obráceně a převede kódy národního prostředí souboru zpět na odpovídající kódy národního prostředí Phrase, včetně `sourceLanguage`. Tato volba ovlivňuje pouze kódy národního prostředí čtené ze souboru .XCSTRINGS a zapisované do něj. Mapování národního prostředí na základě názvu souboru, používané například ve vzorech pojmenování souborů integrace Git, je samostatné nastavení, které mapuje cesty k souborům namísto kódů uvnitř .XCSTRINGS.

Migrace z iOS Strings (.strings) na Strings Catalog (.xcstrings)

Starší formát iOS Strings (.strings) považuje doslovnou sekvenci zpětného lomítka a n (\\n) v obsahu překladu za ekvivalent skutečného konce řádku. V důsledku toho mohou překlady vytvořené nebo upravené při používání formátu .strings obsahovat doslovný text \\n namísto skutečného znaku konce řádku.

Strings Catalog (.xcstrings) je formát založený na JSON. Při exportu obsahu obsahujícího doslovnou sekvenci \n do .xcstrings, kódování JSON tento doslovný text v souboru escapuje jako \\n. Toto chování není chyba dvojitého escapování. Odráží to doslovný text \n, který je již v obsahu překladu přítomen a byl exportován pomocí správného escapování JSON.

Chcete-li toto po migraci z .strings na .xcstrings vyřešit, nahraďte doslovné sekvence \n v dotčeném obsahu skutečnými konci řádků:

Exportujte obsah obvyklým způsobem.
Otevřete exportovaný soubor v textovém editoru.
Nahraďte všechny výskyty doslovné sekvence \n skutečným koncem řádku.
Znovu importujte soubor.

Vyhledávání a nahrazování v aplikaci nepodporuje vkládání skutečného konce řádku, proto musí být tato náhrada provedena v externím textovém editoru před opětovným importem souboru.