.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 stažení souboru. V závislosti na metodě nahrání/stažení (API, CLI, synchronizace repozitáře atd.) mohou být specifikovány v parametrech dotazu `nahrát`, `Stáhnout` nebo v konfiguračním souboru `phrase.yml`.	convert_placeholder default_extraction_state locale_code_mapping

Apple Strings Catalog (.xcstrings) je lokalizační formát 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.

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

Phrase také mapuje stavy překladu Xcode na nejbližší ekvivalenty Strings během importu a převádí je zpět na hodnoty kompatibilní s Xcode při stažení. Pokud se nepoužije žádné konkrétní mapování, jako výchozí hodnota pro stažení se použije přeloženo. V případě potřeby použijte možnost Ignorovat stav překladu při importu 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ásledují exporty 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í stažení:

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í ve 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 množný klíč s názvem %lld Product(s) Ordered|==|device.applewatch do Phrase Strings.

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

{
  "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 substituce přímo v projekt. Když jsou struktury substituce vytvořeny ručně, musí být definován základní klíč a odpovídající klíč substituce, aby byl během stáhnout zajištěn správný vnořený formát.

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

Příklad: Import struktur substituce 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 procesu stáhnout detekuje Phrase Strings substituci pomocí oddělovače a obnoví její původní vnořenou strukturu pro lokalizační formát 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í řetězců substituce od základu

Základní klíč

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

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

Substituční klíč

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

Tento klíč obsahuje text substituce, 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ý znak bude převeden tak, aby odpovídal požadavkům konkrétního formátu. 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í obráceně 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 na základě názvu souboru, 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.

Migrace ze starší 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 obsah 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át .strings obsahovat doslovný text \\n namísto skutečného znak konce řádku.

Strings Catalog (.xcstrings) je formát založený na JSON. Když je obsah obsahující doslovnou sekvenci \\n Stáhnout do .xcstrings, kódování JSON tento doslovný text v souboru escapuje jako \\\\n. Toto chování není chyba dvojitého escapování. Odráží doslovný text \\n již přítomný v obsah překladu, Stáhnout pomocí správného escapování JSON.

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

Stáhnout obsah jako obvykle.
Otevřete stažený soubor v textovém editor.
Nahradit všechny výskyty doslovné sekvence \\n skutečným koncem řádku.
Proveďte import souboru znovu.

Vyhledávání a nahradit v aplikaci nepodporuje vkládání skutečného konce řádku, takže toto nahrazení musí být provedeno v externím textovém editor před opětovným importem souboru.