.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 pueden especificarse cuando un archivo es cargado y/o Descargar. Dependiendo del método de cargar/Descargar (API, CLI, sincronización de repositorio, etc.), pueden especificarse en 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 Strings localizados al admitir formatos estructurados para manejar la pluralización, variaciones específicas de 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 asegurar 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 importar y los convierte de nuevo a valores compatibles con Xcode al exportar. Si no se aplica ninguna asignación específica, translated se usa como el valor de exportar predeterminado. Si es necesario, usar 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 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:

Especifique solo una meta de archivo en el archivo de configuración de la CLI.
Usar el parámetro locale_ids para listar todas las localización de idioma incluidas en la exportación.

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

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

Para manejar variaciones de dispositivo en Phrase Strings, se crean claves separadas para cada dispositivo usando el separador |==|. Al importar archivos .XCSTRINGS, el tipo de dispositivo se añade al nombre de la clave base usando 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 el exportar, Phrase Strings detecta la variante del dispositivo usando el separador y restaura su estructura anidada original para el formato de localización de 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é"
                }
              }
            }
          }
        }
      }
    }
  }
}

Sustituciones de cadena

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

Para manejar sustituciones de cadena en Phrase Strings, se crean claves separadas usando el separador |==|. Al importar archivos .XCSTRINGS, la sustitución se añade al nombre de la clave base usando 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 deben definir una clave base y una clave de sustitución correspondiente para asegurar que se genere el formato anidado correcto durante el exportar.

Las sustituciones siempre requieren un formato de nomenclatura 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 el exportar, Phrase Strings detecta la sustitución usando 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 exportar, 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 usando el formato de nomenclatura de sustitución: keyName|==|substitution.li.

Esta clave contiene el texto de sustitución, normalmente con variaciones plurales. Durante el exportar, Phrase Strings detecta la sustitución usando 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 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` escrito en las claves del archivo exportar cuando no hay un estado de extracción ya definido en la clave. Si una clave ya contiene un `extractionState`, su valor se conserva durante la exportar. Compatibilidad: Descargas de la IU API CLI (mediante la configuración `.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 localización de Phrase a los códigos de localización escritos en el archivo .XCSTRINGS. Cada clave es el código de localización 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 `localización` que coincida con una clave de asignación al valor asignado. Los códigos sin una asignación permanecen sin cambios. Al cargar, Phrase aplica la misma asignación a la inversa y convierte los códigos de localización del archivo de nuevo a los códigos de localización de Phrase correspondientes, incluido `sourceLanguage`. Esta opción afecta solo a los códigos de localización leídos y escritos en el propio archivo .XCSTRINGS. La asignación de localización basada en el nombre de archivo, utilizada por ejemplo en los patrones de nomenclatura de archivos de integración de Git, es una configuración independiente que asigna rutas de archivo en lugar de los códigos dentro de .XCSTRINGS.