.XCSTRINGS - Apple Strings Catalog (Strings)

Контент автоматически переведен с английского языка с помощью Phrase Language AI.

Расширения файлов	.xcstrings
Расширение API	strings_catalog
Импорт	Да
Экспорт	Да
Поддержка форм множественного числа	Да
Поддержка описания	Да
Варианты формата Эти параметры могут быть указаны при загрузке и/или скачивании файла. В зависимости от метода загрузки/скачивания (API, CLI, синхронизация репозитория и т. д.) они могут быть указаны в параметрах запроса `Загрузить`, `Скачать` или в конфигурационном файле `phrase.yml`.	convert_placeholder default_extraction_state

Apple Strings Catalog (.xcstrings) — это формат локализации, введенный в Xcode 15. Он улучшает способ управления локализованными строками разработчиками, поддерживая структурированные форматы для обработки множественного числа, вариаций для конкретных устройств и многое другое. Этот формат становится рекомендуемым подходом для управления локализациями в приложениях iOS и macOS.

Поля метаданных комментарий, состояниеИзвлечения и долженПереводить импортируются и экспортируются в требуемом порядке для обеспечения совместимости с Xcode.

Phrase также сопоставляет состояния перевода Xcode с ближайшими эквивалентами Strings во время импорта и преобразует их обратно в совместимые с Xcode значения при экспорте. Если не применяется конкретное сопоставление, используется переведено в качестве значения экспорта по умолчанию. При необходимости используйте опцию Пропустить состояние перевода при импорте, чтобы пропустить сопоставление состояния.

Образец кода

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

При использовании Phrase CLI экспорт файлов следует структуре, определенной в конфигурационном файле .phrase.yml. Чтобы гарантировать, что несколько языков экспортируются в один файл .XCSTRINGS во время операций извлечения:

Укажите только одну цель файла в конфигурационном файле CLI.
Используйте параметр идентификаторы_языков, чтобы перечислить все языковые стандарты, включенные в экспорт.

Пример .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

Вариации устройств

Apple Strings Catalog поддерживает вариации устройств, которые позволяют использовать разные содержимое перевода для одного и того же ключа в зависимости от используемого устройства Apple.

Чтобы обрабатывать вариации устройств в Phrase Strings, создаются отдельные ключи для каждого устройства с использованием разделителя |==|. При импорте файлов .XCSTRINGS тип устройства добавляется к базовому имени ключа с использованием этого разделителя.

Пример

Ключ с именем %lld Продукт(ов) Заказано для устройства applewatch импортируется как множественный ключ с именем %lld Продукт(ов) Заказано|==|device.applewatch в строках Phrase.

Во время экспорта строки Phrase определяет вариант устройства, используя разделитель, и восстанавливает его оригинальную вложенную структуру для формата локализации Apple.

{
  "sourceLanguage": "en",
  "strings": {
    "%lld Product(s) Ordered": {
      "comment": "Указывает количество заказанных продуктов с вариациями, специфичными для устройства",
      "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é"
                }
              }
            }
          }
        }
      }
    }
  }
}

Замены строк

Каталог строк Apple поддерживает замены строк, которые предоставляют гибкие заполнители для динамического контента.

Для обработки замен строк в строках Phrase создаются отдельные ключи с использованием разделителя |==|. При импорте файлов .XCSTRINGS замена добавляется к базовому имени ключа с использованием этого разделителя.

Строки Phrase также поддерживают создание строк замены непосредственно в проекте. Когда структуры замены создаются вручную, необходимо определить базовый ключ и соответствующий ключ замены, чтобы обеспечить правильный вложенный формат во время экспорта.

Замены всегда требуют конкретного формата именования ключей: keyName|==|substitution.[specifier].

Пример: Импортирование структур замены из существующих файлов .XCSTRINGS

Ключ с именем birdSightingAlert для замены BIRDS импортируется как множественный ключ с именем birdSightingAlert|==|substitution.BIRDS в строках Phrase.

Во время экспорта строки Phrase определяет замену, используя разделитель, и восстанавливает ее оригинальную вложенную структуру для формата локализации 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"
                }
              }
            }
          }
        }
      }
    }
  }

Пример: Создание строк замены с нуля

Базовый ключ

Базовый ключ с именем keyName представляет собой строку формата верхнего уровня, которая содержит заполнитель замены %#@format@.

При экспорте этот ключ записывается как основной stringUnit для записи:
```
"keyName": {
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "translated",
        "value": "%#@format@"
      }
    }
  }
}
```

Ключ замещения

Строка замещения определяется как отдельный ключ с использованием формата именования замещения: keyName|==|substitution.li.

Этот ключ содержит текст замещения, обычно с вариациями во множественном числе. Во время экспорта, Phrase Strings обнаруживает замещение, используя разделитель |==|substitution. и восстанавливает соответствующую вложенную структуру под базовым ключом:

{
  "sourceLanguage": "en",
  "strings": {
    "keyName": {
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "%#@format@"
          },
          "substitutions": {
            "li": {
              "formatSpecifier": "li",
              "variations": {
                "plural": {
                  "one": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ день"
                    }
                  },
                  "other": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ дней"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "version": "1.0"
}

Параметры формата

Идентификатор	convert_placeholder
Тип	булевский
Загрузить	Нет
Скачать	Да
По умолчанию	false
Описание	Заполнитель будет преобразован для соответствия специфическим требованиям формата. Пример: `$s`→`$@`, `%s`→`%@`

Идентификатор	default_extraction_state
Тип	строка
Загрузить	Нет
Скачать	Да
По умолчанию	null
Описание	Определяет значение `extractionState`, записываемое в ключи в экспортируемом файле, когда состояние извлечения еще не определено для ключа. Если ключ уже содержит `extractionState`, его значение сохраняется во время экспорта. Поддерживается в: Загрузки UI Интерфейс приложений API CLI (через `.phrase.yml` конфигурацию) и синхронизацию репозитория