.XCSTRINGS - Apple Strings Catalog (Strings)

Contenuti tradotti automaticamente dall'inglese con Phrase Language AI.

Estensioni dei file	.xcstrings
Estensione API	strings_catalog
Importa	Sì
Esporta	Sì
Supporto forme plurali	Sì
Supporto descrizione	Sì
Opzioni di formato Queste opzioni possono essere specificate quando un file viene caricato e/o scaricato. A seconda del metodo di caricamento/scaricamento (API, CLI, sincronizzazione Repo ecc.), possono essere specificate nei parametri di query `caricare`, `Scarica` o nel file di configurazione `phrase.yml`.	convert_placeholder default_extraction_state locale_code_mapping

Apple Strings Catalog (.xcstrings) è un formato di localizzazione introdotto in Xcode 15. Migliora il modo in cui gli sviluppatori gestiscono le stringhe localizzate supportando formati strutturati per gestire la pluralizzazione, le variazioni specifiche del dispositivo e altro ancora. Questo formato sta diventando l'approccio consigliato per gestire le localizzazioni nelle applicazioni iOS e macOS.

I campi di metadati commentare, extractionState e shouldTranslate vengono importati ed esportati nell'ordine richiesto per garantire la compatibilità con Xcode.

Phrase mappa anche gli stati di traduzione di Xcode agli equivalenti di Strings più vicini durante l'importazione e li converte nuovamente in valori compatibili con Xcode durante l'esportazione. Se non si applica alcuna mappatura specifica, translated viene usato come valore di esportazione predefinito. Se necessario, usare l'opzione Ignore translation state on import per saltare la mappatura dello stato.

Esempio di codice

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

Quando si usa la Phrase CLI, le esportazioni di file seguono la struttura definita nel file di configurazione .phrase.yml. Per garantire che più lingue vengano esportate in un singolo file .XCSTRINGS durante le operazioni di pull:

Specificare una sola destinazione file nel file di configurazione CLI.
Usare il parametro locale_ids per elencare tutte le impostazioni locali di lingua incluse nell'esportazione.

Esempio di configurazione .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

Variazioni dispositivo

Apple Strings Catalog supporta le variazioni di dispositivo, che consentono contenuti di traduzione diversi per la stessa chiave a seconda del dispositivo Apple utilizzato.

Per gestire le variazioni di dispositivo in Phrase Strings, vengono create chiavi separate per ogni dispositivo usando il separatore |==|. Durante l'importazione di file .XCSTRINGS, il tipo di dispositivo viene aggiunto al nome della chiave base usando questo separatore.

Esempio

La chiave denominata %lld Product(s) Ordered per il dispositivo applewatch viene importata come chiave plurale denominata %lld Product(s) Ordered|==|device.applewatch in Phrase Strings.

Durante l'esportazione, Phrase Strings rileva la variante di dispositivo usando il separatore e ripristina la sua struttura nidificata originale per il formato di localizzazione 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é"
                }
              }
            }
          }
        }
      }
    }
  }
}

Sostituzioni di stringa

Apple Strings Catalog supporta le sostituzioni di stringa che forniscono segnaposto flessibili per il contenuto dinamico.

Per gestire le sostituzioni di stringa in Phrase Strings, vengono create chiavi separate utilizzando il separatore |==|. Quando si importano file .XCSTRINGS, la sostituzione viene aggiunta al nome della chiave base utilizzando questo separatore.

Phrase Strings supporta anche la creazione di stringhe di sostituzione direttamente nel progetto. Quando le strutture di sostituzione vengono create manualmente, devono essere definite una chiave base e una chiave di sostituzione corrispondente per garantire che venga generato il formato nidificato corretto durante l'esportazione.

Le sostituzioni richiedono sempre un formato di denominazione della chiave specifico: keyName|==|substitution.[specifier].

Esempio: Importazione di strutture di sostituzione da file .XCSTRINGS esistenti

La chiave denominata birdSightingAlert per la sostituzione BIRDS viene importata come chiave plurale denominata birdSightingAlert|==|substitution.BIRDS in Phrase Strings.

Durante l'esportazione, Phrase Strings rileva la sostituzione utilizzando il separatore e ripristina la sua struttura nidificata originale per il formato di localizzazione di 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"
                }
              }
            }
          }
        }
      }
    }
  }

Esempio: Creazione di stringhe di sostituzione da zero

Chiave base

Una chiave base denominata keyName rappresenta la stringa di formato di primo livello che contiene il segnaposto %#@format@.

Quando esportata, questa chiave viene scritta come stringUnit primaria per la voce:
```
"keyName": {
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "translated",
        "value": "%#@format@"
      }
    }
  }
}
```

Chiave di sostituzione

Una stringa di sostituzione viene definita come chiave separata utilizzando il formato di denominazione della sostituzione: keyName|==|substitution.li.

Questa chiave contiene il testo di sostituzione, solitamente con variazioni plurali. Durante l'esportazione, Phrase Strings rileva la sostituzione utilizzando il separatore |==|substitution. e ripristina la struttura nidificata corrispondente sotto la chiave base:

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

Opzioni di formato

Identificatore	convert_placeholder
Tipo	booleano
Caricamento	No
Download	Sì
Predefinito	false
Descrizione	Il segnaposto verrà convertito per corrispondere ai requisiti specifici del formato. Esempio: `$s`→`$@`, `%s`→`%@`

Identificatore	default_extraction_state
Tipo	stringa
Caricamento	No
Download	Sì
Predefinito	null
Descrizione	Definisce il valore `extractionState` scritto nelle chiavi nel file esportato quando non è già definito alcuno stato di estrazione sulla chiave. Se una chiave contiene già uno `extractionState`, il suo valore viene preservato durante l'esportazione. Supporta: Download dell'interfaccia utente API CLI (tramite configurazione `.phrase.yml`) e Repo Sync

Identificatore	locale_code_mapping
Tipo	oggetto
Caricamento	Sì
Download	Sì
Predefinito	{}
Descrizione	Mappa i codici delle impostazioni locali di Phrase ai codici delle impostazioni locali scritti nel file .XCSTRINGS. Ogni chiave è il codice delle impostazioni locali di Phrase; ogni valore è il codice scritto nel file, ad esempio: { "en": "en-GB", "fr": "fr-FR" } Al download, Phrase riscrive il campo `sourceLanguage` e qualsiasi chiave `localizations` che corrisponde a una chiave di mappatura con il valore mappato. I codici senza una mappatura rimangono invariati. Al caricamento, Phrase applica la stessa mappatura al contrario e converte i codici delle impostazioni locali del file nei corrispondenti codici delle impostazioni locali di Phrase, incluso `sourceLanguage`. Questa opzione influisce solo sui codici delle impostazioni locali letti e scritti nel file .XCSTRINGS stesso. La mappatura delle impostazioni locali basata sul nome file, utilizzata ad esempio nei pattern di denominazione dei file di integrazione Git, è un'impostazione separata che mappa i percorsi dei file anziché i codici all'interno di .XCSTRINGS.