.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, при экспортировать. Если никакое конкретное сопоставление не применяется, перевод используется в качестве значения по умолчанию при экспортировать. При необходимости используйте параметр пропустить состояние перевода при импорте, чтобы пропустить сопоставление состояний.

Образец кода

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

Во время экспорта 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é"
                }
              }
            }
          }
        }
      }
    }
  }
}

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

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

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

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

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

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

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

Во время экспорта 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"
                }
              }
            }
          }
        }
      }
    }
  }

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

Базовый ключ

Базовый ключ с именем 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`, его значение сохраняется во время экспорта. Поддерживаются: Скачивание через интерфейс Интерфейс приложений 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.

Миграция с iOS Strings (.strings) на Strings Catalog (.xcstrings)

Устаревшая версия формат iOS Strings (.strings) обрабатывает последовательность литерала обратной косой черты с n (\\n) в контент перевода как эквивалент реального разрыва строки. В результате переводы, созданные или отредактированные при использовании формат .strings, могут содержать текст литерала \\n вместо фактического символ разрыва строки.

Strings Catalog (.xcstrings) — это формат на основе JSON. Когда контент, содержащий последовательность литерала \\n, выполняется Экспорт в .xcstrings, кодировка JSON экранирует этот текст литерала как \\\\n в файле. Это поведение не является ошибкой двойного экранирования. Оно отражает текст литерала \\n, уже присутствующий в контент перевода, который был выполнен Экспорт с использованием правильного экранирования JSON.

Чтобы устранить это после миграции с .strings на .xcstrings, Заменить последовательности литерала \\n в затронутом контенте на реальные разрывы строк:

Экспорт контент как обычно.
Откройте экспортированный файл в текстовом редактор.
Заменить все экземпляры последовательности литерала \\n на реальный разрыв строки.
Повторно импортировать файл.

Поиск и заменить в приложении не поддерживает вставку реального разрыва строки, поэтому это Заменить необходимо выполнить во внешнем текстовом редактор перед повторным импортом файла.