.XCSTRINGS - Каталог строк Apple (Строки)

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

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

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

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

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

Образец кода

{
  "sourceLanguage": "en",
  "strings": {
    "Sync Warning": {
      "comment": "Сообщение о недоступности функции синхронизации",
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Для использования этой функции необходимо включить облачную синхронизацию."
          }
        },
        "fr": {
          "stringUnit": {
            "state": "translated",
            "value": "Облачная синхронизация должна быть включена для использования этой функции."
          }
        }
      }
    },
    "Chosen Collections": {
      "comment": "Заголовок просмотра, указывающий на выбранные коллекции фотографий",
      "localizations": {
        "fr": {
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld коллекция выбрана"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld коллекций выбрано"
                }
              }
            }
          }
        },
        "en": {
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld Коллекция Выбрана"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld Выбранные коллекции"
                }
              }
            }
          }
        }
      }
    },
    "Центр настроек": {
      "localizations": {
        "es": {
          "stringUnit": {
            "state": "translated",
            "value": "Centro de configuración"
          }
        }
      }
    }
  },
  "version": "1.0"
}

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

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

Пример .phrase.yml конфигурации

извлечение:
  цели:
    - файл: ./i18n-test/Localizable.xcstrings
      параметры:
        locale_id: en # Основной язык для скачивания
        locale_ids: # Дополнительные языки для включения
          - de
          - es
          - fr 
        file_format: strings_catalog

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

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

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

Пример

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

Во время экспорта строки фраз определяют вариант устройства с использованием разделителя и восстанавливают его оригинальную вложенную структуру для формата локализации 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 Продукт заказан (Mac)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Продукта заказано (Mac)"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "fr": {
          "variations": {
            "plural": {
              "few": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld продукт(ов) заказано"
                }
              },
              "many": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld продуктов заказано"
                }
              },
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld продукт заказан"
                }
              }
            }
          }
        }
      }
    }
  }
}

Замены строк

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

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

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

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

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

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

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

"birdSightingAlert": {
  "comment": "Сообщение оповещения, указывающее количество замеченных птиц",
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "новый",
        "value": "Вы заметили %#@BIRDS@!"
      },
      "substitutions": {
        "BIRDS": {
          "formatSpecifier": "BIRDS",
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "новый",
                  "value": "птица"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "новый",
                  "value": "несколько птиц"
                }
              },
              "zero": {
                "stringUnit": {
                  "state": "новый",
                  "value": "нет птиц"
                }
              }
            }
          }
        }
      }
    }
  }

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

Базовый ключ

Базовый ключ с именем 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`, его значение сохраняется при экспорте. Поддерживается в: Загрузках интерфейса пользователя ИНТЕРФЕЙС ПРИЛОЖЕНИЙ API CLI (через конфигурацию `.phrase.yml`) и синхронизацию репозитория