.XCSTRINGS - Apple Strings Catalog (Strings)

El contenido se traduce automáticamente del inglés por Phrase Language AI.

Extensiones de archivo	.xcstrings
Extensión API	strings_catalog
Importación	Sí
Exportación	Sí
Compatibilidad con formularios plurales	Sí
Compatibilidad con descripción	Sí
Opciones de formato Estas son las opciones que se pueden especificar cuando se carga y/o descarga un archivo. Dependiendo del método de carga/descarga (API, CLI, sincronización de repositorio, etc.), se pueden especificar en los parámetros de consulta `Upload`, `Download` o en el archivo de configuración `phrase.yml`.	convert_placeholder default_extraction_state locale_code_mapping

Apple Strings Catalog (.xcstrings) es un formato de localización introducido en Xcode 15. Mejora la forma en que los desarrolladores gestionan las cadenas localizadas al admitir formatos estructurados para manejar la pluralización, las variaciones específicas del dispositivo y más. Este formato se está convirtiendo en el enfoque recomendado para gestionar localizaciones en aplicaciones de iOS y macOS.

Los campos de metadatos comment, extractionState y shouldTranslate se importan y exportan en el orden requerido para garantizar la compatibilidad con Xcode.

Phrase también asigna los estados de traducción de Xcode a los equivalentes de Strings más cercanos durante la importación y los convierte de nuevo a valores compatibles con Xcode durante la exportación. Si no se aplica ninguna asignación específica, se utiliza translated como valor de exportación predeterminado. Si es necesario, usa la opción Ignore translation state on import para omitir la asignación de estado.

Ejemplo de código

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

Al utilizar Phrase CLI, las exportaciones de archivos siguen la estructura definida en el archivo de configuración .phrase.yml. Para garantizar que se exporten varios idiomas a un único archivo .XCSTRINGS durante las operaciones de extracción:

Especifica solo un destino de archivo en el archivo de configuración de la CLI.
Utiliza el parámetro locale_ids para enumerar todos los locales de idioma incluidos en la exportación.

Ejemplo de configuración de .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

Variaciones de dispositivo

El Catálogo de cadenas de Apple admite variaciones de dispositivo, que permiten diferentes contenidos de traducción para la misma clave según el dispositivo Apple que se utilice.

Para gestionar las variaciones de dispositivo en Phrase Strings, se crean claves separadas para cada dispositivo utilizando el separador |==|. Al importar archivos .XCSTRINGS, el tipo de dispositivo se añade al nombre de la clave base utilizando este separador.

Ejemplo

La clave llamada %lld Product(s) Ordered para el dispositivo applewatch se importa como una clave plural llamada %lld Product(s) Ordered|==|device.applewatch en Phrase Strings.

Durante la exportación, Phrase Strings detecta la variante de dispositivo utilizando el separador y restaura su estructura anidada original para el formato de localización de Apple.

{
  "sourceLanguage": "en",
  "strings": {
    "%lld Product(s) Ordered": {
      "comment": "Indica la cantidad de productos pedidos, con variaciones específicas para cada 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é"
                }
              }
            }
          }
        }
      }
    }
  }
}

Sustituciones de cadenas

Apple Strings Catalog admite sustituciones de cadenas que proporcionan marcadores de posición flexibles para contenido dinámico.

Para gestionar las sustituciones de cadenas en Phrase Strings, se crean claves separadas utilizando el separador |==|. Al importar archivos .XCSTRINGS, la sustitución se añade al nombre de la clave base utilizando este separador.

Phrase Strings también admite la creación de cadenas de sustitución directamente en el proyecto. Cuando crees estructuras de sustitución manualmente, define una clave base y una clave de sustitución correspondiente para garantizar que se genere el formato anidado correcto durante la exportación.

Las sustituciones siempre requieren un formato de nombre de clave específico: keyName|==|substitution.[specifier].

Ejemplo: Importación de estructuras de sustitución desde archivos .XCSTRINGS existentes

La clave llamada birdSightingAlert para la sustitución BIRDS se importa como una clave plural llamada birdSightingAlert|==|substitution.BIRDS en Phrase Strings.

Durante la exportación, Phrase Strings detecta la sustitución utilizando el separador y restaura su estructura anidada original para el formato de localización de 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"
                }
              }
            }
          }
        }
      }
    }
  }

Ejemplo: Creación de cadenas de sustitución desde cero

Clave base

Una clave base llamada keyName representa la cadena de formato de nivel superior que contiene el marcador de posición de sustitución %#@format@.

Al exportarse, esta clave se escribe como la stringUnit principal para la entrada:
```
"keyName": {
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "translated",
        "value": "%#@format@"
      }
    }
  }
}
```

Clave de sustitución

Una cadena de sustitución se define como una clave separada utilizando el formato de nomenclatura de sustitución: keyName|==|substitution.li.

Esta clave contiene el texto de sustitución, normalmente con variaciones en plural. Durante la exportación, Phrase Strings detecta la sustitución utilizando el separador |==|substitution. y restaura la estructura anidada correspondiente bajo la clave 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.
}

Opciones de formato

Identificador	convert_placeholder
Tipo	Booleano
Carga	No
Descarga	Sí
Por defecto	false
Descripción	El marcador de posición se convertirá para cumplir con los requisitos específicos del formato. Ejemplo: `$s`→`$@`, `%s`→`%@`

Identificador	default_extraction_state
Tipo	cadena
Carga	No
Descarga	Sí
Por defecto	null
Descripción	Define el valor de `extractionState` que se escribe en las claves del archivo exportado cuando no hay ningún estado de extracción definido previamente en la clave. Si una clave ya contiene un `extractionState`, su valor se conserva durante la exportación. Disponible en: Descargas de la UI API CLI (mediante la configuración de `.phrase.yml`) y sincronización de repositorios

Identificador	locale_code_mapping
Tipo	objeto
Carga	Sí
Descarga	Sí
Por defecto	}
Descripción	Asigna los códigos de idioma de Phrase a los códigos de idioma escritos en el archivo .XCSTRINGS. Cada clave es el código de idioma de Phrase; cada valor es el código escrito en el archivo, por ejemplo: { "en": "en-GB", "fr": "fr-FR" } Al descargar, Phrase reescribe el campo `sourceLanguage` y cualquier clave de `localizations` que coincida con una clave de mapeo al valor mapeado. Los códigos sin un mapeo permanecen sin cambios. Al cargar, Phrase aplica el mismo mapeo a la inversa y convierte los códigos de configuración regional del archivo de nuevo a los códigos de configuración regional de Phrase correspondientes, incluido `sourceLanguage`. Esta opción afecta solo a los códigos de configuración regional leídos y escritos en el propio archivo .XCSTRINGS. El mapeo de configuración regional basado en nombres de archivo, utilizado por ejemplo en patrones de nombres de archivos de integración de Git, es una configuración separada que mapea rutas de archivo en lugar de los códigos dentro de .XCSTRINGS.

Migración de iOS Strings (.strings) a Strings Catalog (.xcstrings)

El formato heredado de iOS Strings (.strings) trata una secuencia literal de barra invertida-n (\\n) en el contenido de la traducción como equivalente a un salto de línea real. Como resultado, las traducciones creadas o editadas mientras se utiliza el formato .strings pueden contener el texto literal \\n en lugar de un carácter de salto de línea real.

Strings Catalog (.xcstrings) es un formato basado en JSON. Cuando el contenido que contiene una secuencia literal \\n se exporta a .xcstrings, la codificación JSON escapa ese texto literal como \\\\n en el archivo. Este comportamiento no es un error de doble escape. Refleja el texto literal \\n ya presente en el contenido de la traducción, exportado utilizando el escape JSON correcto.

Para resolver esto después de migrar de .strings a .xcstrings, reemplaza las secuencias literales \\n en el contenido afectado con saltos de línea reales:

Exporta el contenido como de costumbre.
Abre el archivo exportado en un editor de texto.
Reemplaza todas las instancias de la secuencia literal \\n con un salto de línea real.
Vuelve a importar el archivo.

La búsqueda y el reemplazo dentro de la aplicación no soportan insertar un salto de línea real, así que haz este reemplazo en un editor de texto externo antes de volver a importar el archivo.