.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 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 repositorios, etc.), se pueden especificar en parámetros de consulta `Cargar`, `Descargar` o en el archivo de configuración `phrase.yml`.	convert_placeholder default_extraction_state

Apple Strings Catalog (.xcstrings) es un formato de localización introducido en Xcode 15. Mejora la forma en que los desarrolladores gestionan cadenas localizadas al admitir formatos estructurados para manejar pluralización, variaciones específicas de dispositivos 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 comentar, estadoDeExtracción y deberíaTraducir se importan y exportan en el orden requerido para garantizar la compatibilidad con Xcode.

Phrase también mapea los estados de traducción de Xcode a los equivalentes más cercanos de Strings durante la importación y los convierte de nuevo a valores compatibles con Xcode en la exportación. Si no se aplica un mapeo específico, se utiliza traducido como el valor de exportación predeterminado. Si es necesario, utiliza la opción Ignorar estado de traducción en la importación para omitir el mapeo 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 usar Phrase CLI, las exportaciones de archivos siguen la estructura definida en el archivo de configuración .phrase.yml. Para asegurar que múltiples idiomas se exporten en un solo archivo .XCSTRINGS durante las operaciones de extracción:

Especifica solo un objetivo de archivo en el archivo de configuración de la CLI.
Utiliza el parámetro locale_ids para listar todas las localizaciones de idioma incluidas en la exportación.

Ejemplo .phrase.yml configuración

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

Apple Strings Catalog admite variaciones de dispositivo, que permiten diferentes contenidos de traducción para la misma clave dependiendo del dispositivo Apple que se esté utilizando.

Para manejar 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 Producto(s) Ordenado(s) para el dispositivo applewatch se importa como una clave plural llamada %lld Producto(s) Ordenado(s)|==|device.applewatch en Phrase Strings.

Durante la exportación, Phrase Strings detecta la variante del 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 el número de productos pedidos, con variaciones específicas del 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

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

Para manejar 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 las estructuras de sustitución se crean manualmente, se debe definir una clave base y una clave de sustitución correspondiente para asegurar que se genere el formato anidado correcto durante la exportación.

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

Ejemplo: Importando estructuras de sustitución de 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: Creando 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@.

Cuando se exporta, 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 nombrado de sustitución: keyName|==|substitution.li.

Esta clave contiene el texto de sustitución, típicamente 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": "%@ día"
                    }
                  },
                  "other": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ días"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "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 coincidir con los requisitos específicos del formato. Ejemplo: `$s`→`$@`, `%s`→`%@`

Identificador	default_extraction_state
Tipo	cadena
Carga	No
Descarga	Sí
Por defecto	nulo
Descripción	Define el valor `extractionState` escrito en las claves en el archivo exportado cuando no se ha definido un estado de extracción en la clave. Si una clave ya contiene un `extractionState`, su valor se preserva durante la exportación. Compatible en: Descargas de UI API CLI (a través de la configuración `.phrase.yml`) y Sincronización de Repositorios