.XCSTRINGS - Catalogo delle stringhe Apple (Stringhe)

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 `Upload`, `Download` 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 la gestione della pluralizzazione, le variazioni specifiche del dispositivo e altro ancora. Questo formato sta diventando l'approccio consigliato per la gestione delle localizzazioni nelle applicazioni iOS e macOS.

I campi di metadati comment, 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 Stringhe 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 utilizzato come valore di esportazione predefinito. Se necessario, utilizza 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 utilizza Phrase CLI, le esportazioni dei file seguono la struttura definita nel file di configurazione .phrase.yml. Per garantire che più lingue vengano esportate in un unico file .XCSTRINGS durante le operazioni di pull:

Specifica un solo file di destinazione nel file di configurazione CLI.
Utilizza il parametro locale_ids per elencare tutte le impostazioni locali della 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 del 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 del dispositivo in Phrase Strings, vengono create chiavi separate per ogni dispositivo utilizzando il separatore |==|. Durante l'importazione di file .XCSTRINGS, il tipo di dispositivo viene aggiunto al nome della chiave di base utilizzando 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 del dispositivo utilizzando il separatore e ripristina la sua struttura nidificata originale per il formato di localizzazione di Apple.

{
  "sourceLanguage": "en",
  "strings": {
    "%lld Product(s) Ordered": {
      "comment": "Indica il numero di prodotti ordinati, con variazioni specifiche per dispositivo",
      "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 stringhe

Apple Strings Catalog supporta le sostituzioni di stringhe che forniscono segnaposto flessibili per contenuti dinamici.

Per gestire le sostituzioni di stringhe in Phrase Strings, vengono create chiavi separate utilizzando il separatore |==|. Quando si importano file .XCSTRINGS, la sostituzione viene aggiunta al nome della chiave di 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, è necessario definire una chiave di base e una corrispondente chiave di sostituzione 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 di base

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

Quando esportata, questa chiave viene scritta come stringUnit principale 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 varianti plurali. Durante l'esportazione, Phrase Strings rileva la sostituzione utilizzando il separatore |==|substitution. e ripristina la corrispondente struttura nidificata 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": "%@ giorno"
                    }
                  },
                  "other": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ giorni"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "version": 1.0
}

Opzioni di formato

Identificatore	convert_placeholder
Tipo	booleano
Caricamento	No
Download	Sì
Predefinito	false
Descrizione	Il segnaposto verrà convertito per soddisfare i 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à un `extractionState`, il suo valore viene preservato durante l'esportazione. Supportato in: Download dall'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 lingua di Phrase ai codici lingua scritti nel file .XCSTRINGS. Ogni chiave è il codice lingua 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 modelli di denominazione dei file di integrazione Git, è un'impostazione separata che mappa i percorsi dei file anziché i codici all'interno di .XCSTRINGS.

Migrazione da iOS Strings (.strings) a Strings Catalog (.xcstrings)

Il formato legacy iOS Strings (.strings) tratta una sequenza letterale backslash-n (\\n) nel contenuto della traduzione come equivalente a un'interruzione di riga reale. Di conseguenza, le traduzioni create o modificate durante l'utilizzo del formato .strings possono contenere il testo letterale \\n invece di un carattere di interruzione di riga effettivo.

Strings Catalog (.xcstrings) è un formato basato su JSON. Quando il contenuto contenente una sequenza letterale \\n viene esportato in .xcstrings, la codifica JSON esegue l'escape di quel testo letterale come \\\\n nel file. Questo comportamento non è un errore di doppio escape. Riflette il testo letterale \\n già presente nel contenuto della traduzione, esportato utilizzando il corretto escape JSON.

Per risolvere il problema dopo la migrazione da .strings a .xcstrings, sostituisci le sequenze letterali \\n nel contenuto interessato con interruzioni di riga reali:

Esporta il contenuto come di consueto.
Apri il file esportato in un editor di testo.
Sostituisci tutte le occorrenze della sequenza letterale \n con un'interruzione di riga reale.
Reimporta il file.

La funzione di ricerca e sostituzione nell'app non supporta l'inserimento di un'interruzione di riga reale, pertanto questa sostituzione deve essere eseguita in un editor di testo esterno prima di reimportare il file.