.XCSTRINGS — Каталог строк Apple (Strings)

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

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

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

Поля метаданных comment, 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 поддерживает варианты устройств, которые позволяют использовать разное содержимое перевода для одного и того же ключа в зависимости от используемого устройства 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": «Указывает количество заказанных товаров с учетом вариаций для разных устройств»,
      "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 на реальный разрыв строки.
Повторно импортируйте файл.

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