.XCSTRINGS - Apple Strings Catalog (Strings)

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

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

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

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

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

Образец кода

{
  "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 во время операций pull:

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

Пример конфигурации .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 Product(s) Ordered для устройства applewatch импортируется как ключ множественного числа с именем %lld Product(s) Ordered|==|device.applewatch в Phrase Strings.

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

Подстановки Strings

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

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

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

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

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

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

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

Пример: Создание Strings с заменой с нуля

Базовый ключ

Базовый ключ с именем 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\": \"%@ day\"
                    }
                  },
                  "other": {
                    "stringUnit": {
                      "state": "translated",
                      \"value\": \"%@ days\"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "version": "1.0"
}

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

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

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

Идентификатор	locale_code_mapping
Тип	объект
Загрузить	Да
Скачать	Да
По умолчанию	{}
Описание	Сопоставляет коды языковой стандарт Phrase с кодами языковой стандарт, записанными в файл .XCSTRINGS. Каждый ключ — это код языковой стандарт Phrase; каждое значение — это код, записанный в файл, например: { \"en\": \"en-GB\"," \"fr\": \"fr-FR\" } При скачивание Phrase перезаписывает поле `sourceLanguage` и любой ключ `localizations`, который совпадение с ключ сопоставления, на сопоставленное значение. Коды без сопоставления остаются без изменений. При загрузить Phrase применяет то же сопоставление в обратном порядке и преобразует коды языковой стандарт файла обратно в соответствующие коды языковой стандарт Phrase, включая `sourceLanguage`. Этот параметр влияет только на коды языкового стандарта, считываемые из файла .XCSTRINGS и записываемые в него. Сопоставление языкового стандарта на основе имени файла, используемое, например, в шаблонах именования файлов для интеграция с Git, является отдельным параметром, который сопоставляет пути к файлам, а не коды внутри .XCSTRINGS.