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

Это руководство предназначено для тех, кто проверяет локализованные метки приложения для Mac в Xcode. Задача — сверить одно сообщение и его переводы со значениями, передаваемыми приложением. Все приведённые ниже метки — условные примеры на английском языке; они иллюстрируют форматирование, а не реальные переводы.

Что входит в контракт аргументов сообщения?

Контракт аргументов — это запись для проверки, описывающая значения, которые получает сообщение: их позиции, типы форматирования, значения и предполагаемое использование. Это практический список, составленный на основе исходного кода и каталога, а не отдельный файловый формат Apple.

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

Рассмотрим форматную строку Added %lld items to %@. В этом примере приложение передаёт целочисленное количество, а затем метку коллекции, представленную объектом. Прежде чем редактировать перевод, запишите контракт:

Позиция аргумента Значение Ожидаемый формат Пример значения
1 Количество добавленных элементов %lld 7
2 Метка целевой коллекции %@ Canvas

Согласно справочнику форматов Apple, %@ — это преобразование объекта, %d — 32-разрядного целого со знаком, %f — числа с плавающей точкой двойной точности, а ll — модификатор длины для long long. В справочнике также описаны позиционные формы, например %1$@. Сохраняйте полную информацию о типе: замена %lld на %d меняет ожидаемый тип целого числа. Справочник архивный, поэтому используйте его для синтаксиса форматов вместе с актуальной документацией по каталогам. String Format Specifiers

Добавляйте в запись для проверки значения аргументов, даже если их типы совпадают. Для строки Moved %@ to %@ проверка типа не поможет отличить метку элемента от метки места назначения. Правильный синтаксис ещё не гарантирует, что значения связаны с нужными словами.

Как найти в Xcode авторитетный источник?

Откройте проект в Xcode и найдите каталог, содержащий сообщение. Если исходный код изменился, выберите Product > Build, чтобы обновить извлечённые строки. Выберите каталог в навигаторе проекта, затем Editor > Assistant и выберите ключ сообщения, чтобы просмотреть его источник. Apple описывает этот процесс поиска и обновления записей каталога. Localizing and varying text with a string catalog

Проверьте, какие значения фактически передаются в месте вызова, в каком порядке и через какой API локализации. Apple рекомендует локализуемые API, например String(localized:); инициализатор с отдельным defaultValue использует первый параметр как ключ, а второй — как исходную строку по умолчанию. Это важно, когда сообщение связано с нейтральным идентификатором вроде collection.added.summary. Preparing your app’s text for translation

Зафиксируйте вместе три вещи: каталог и ключ, исходный текст по умолчанию, а также значения и типы аргументов в заданном порядке. Если эти сведения расходятся, устраните несоответствие до правки переводов. Иначе перевод может соответствовать устаревшему источнику, а не текущим входным данным приложения.

Добавьте контекст и для будущих правок. Apple поддерживает комментарии к локализуемым строкам, поясняющие их использование. Полезный условный комментарий мог бы указать, что аргумент 1 — количество элементов, а аргумент 2 — метка целевой коллекции. Это передаёт локализатору сведения, которые не выразить спецификатором формата. Preparing your app’s text for translation

Как проверить количество, типы и позиции аргументов?

Apple добавила проверку каталогов строк на распространённые проблемы, включая несоответствия спецификаторов формата; для некоторых проблем доступны исправления. Просмотрите все диагностические сообщения Xcode для записи. Предлагаемое исправление считайте вариантом исправления синтаксиса и проверьте, сохраняет ли оно смысл сообщения. Build multilingual-ready apps

Для простого сообщения без подстановок множественного числа используйте такой порядок проверки:

  1. Найдите все плейсхолдеры в исходном и проверяемом тексте, которые принимают аргументы.
  2. Сопоставьте каждый плейсхолдер с позицией аргумента.
  3. Сравните полный тип формата с контрактом.
  4. Убедитесь, что каждое необходимое значение стоит там, где этого требует формулировка.
  5. Отдельно разберите добавленные, пропущенные или повторяющиеся ссылки на аргументы.

Позиционная нотация позволяет менять порядок слов в переводе, сохраняя связь с аргументами. В %2$@: added %1$lld items первый видимый плейсхолдер ссылается на аргумент 2, а второй — на аргумент 1. Apple описывает позиционный синтаксис n$. String Format Specifiers

Ниже приведена таблица решений для условного контракта с двумя аргументами. Это предлагаемые результаты проверки, а не итоги запуска Xcode:

Текст с форматами Результат проверки Причина
Added %lld items to %@ Соответствует простому контракту Сначала количество, затем целевая коллекция
%2$@: added %1$lld items Соответствует после перестановки Явные позиции сохраняют связь с обоими аргументами
Added %d items to %@ Исправьте тип целого числа У аргумента 1 больше нет ожидаемого модификатора длины
Added %lld items Разберите пропуск В сообщении отсутствует обязательное место назначения
Added %1$lld items to %1$@ Исправьте ссылки Аргумент 1 используется с несовместимыми типами; аргумент 2 отсутствует
Added %1$lld items to %2$@ (%2$@) Проверьте повторение Здесь три вхождения, но только на два разных аргумента есть ссылки

Не смешивайте количество вхождений с количеством разных аргументов. В последней строке это различие показано намеренно: повторное использование аргумента 2 не создаёт третьего переданного значения. Уместно ли это повторение в формулировке — редакторское решение. В рамках этой проверки отметьте его, пока причина не будет установлена.

Также не считайте каждый символ процента аргументом. Apple определяет %% как литеральный знак процента. Форматная строка метки Scale: %lld%% содержит один плейсхолдер значения и один экранированный знак процента. String Format Specifiers

Почему подстановки множественного числа требуют отдельной проверки?

Для сообщений с множественным числом нужно проверить не только отображаемый текст, но и механизм выбора варианта. В докладе о каталогах строк Apple объясняет, что подстановки могут содержать словари с вариантами для разных форм множественного числа. Инспектор показывает позицию управляющего аргумента и спецификатор формата в стиле C. Поэтому подстановка может зависеть от аргумента, даже если в конкретной ветви этот аргумент не отображается числом. Discover String Catalogs

Для условного сообщения о количестве элементов сравните One item added и %lld items added. В первой ветви количество написано словами, во второй — выводится числом. Правило, требующее одинакового количества видимых плейсхолдеров в каждой ветви, неоправданно отклонило бы первый вариант. В описании поведения словаря strings Apple прямо допускает опускать числовой спецификатор формата в формах множественного числа и приводит запись числа словами как один из вариантов. Stringsdict file format

Используйте вместо этого проверку с учётом ветвей:

  • Проверьте в инспекторе позицию и тип управляющего аргумента подстановки.
  • Просмотрите все ветви множественного числа, имеющиеся для целевой локали.
  • Сверьте каждый отображаемый плейсхолдер с аргументом, на который он ссылается.
  • Если числовое значение не отображается, убедитесь, что это объясняется формулировкой ветви.
  • Отдельно проверьте остальные аргументы сообщения: запись количества словами не объясняет отсутствие метки коллекции.

Для двух независимо изменяющихся количеств сохраняйте их отдельные роли. В условном сообщении об элементах и коллекциях количество элементов должно управлять подстановкой для элементов, а количество коллекций — подстановкой для коллекций. Apple описывает несколько подстановок в одном сообщении и поясняет, что вывод во время выполнения объединяет выбранные варианты множественного числа. Discover String Catalogs

Как проверить исправленное сообщение на Mac?

После исправления записи соберите приложение и просмотрите оставшиеся диагностические сообщения каталога. Затем откройте нужный экран в целевой локали. Поддерживаемый Apple порядок действий: выбрать Product > Scheme > Edit Scheme, выбрать Run, открыть Options, выбрать App Language и соответствующий App Region, нажать Close, а затем запустить выбранное устройство. Testing localizations when running your app

Выбирайте тестовые значения, с которыми перестановки легко заметить. Для двух аргументов-чисел используйте разные числа, например 2 и 7. Для двух текстовых аргументов подойдут разные метки, например Tile и Canvas. Это примерные тестовые входные данные: они нужны, чтобы увидеть, какое переданное значение появляется в каждой части сообщения.

Для сообщений с множественным числом проверьте значения, ведущие к рассматриваемым ветвям. Если две подстановки меняются независимо, включите комбинации, в которых одно количество меняется, а другое остаётся прежним. Проверьте выбранную формулировку и расположение каждого отображаемого значения. Успешный вывод для одной комбинации ничего не говорит о непроверенных ветвях.

Отделяйте состояние перевода от проверки контракта. Apple поясняет, что зелёная галочка в каталоге означает переведённое состояние после ввода текста. Записывайте выполненные проверки — сопоставление аргументов, сравнение типов, просмотр ветвей и проверку отображаемых примеров, — а не считайте этот индикатор подтверждением всех четырёх. Localizing and varying text with a string catalog

Сообщение готово к дальнейшей работе, когда его плейсхолдеры соответствуют нужным переданным аргументам, типы совпадают, а пропуск или повторение в конкретной ветви имеет понятное объяснение. Если хранить этот краткий контракт рядом с сообщением, следующие изменения исходного текста или перевода будет проще оценивать.

Источники