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

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

Определите, что считается завершённым сообщением

Начните с небольшой рабочей таблицы проверки. Запишите цель приложения, пакет ресурсов, таблицу строк, ключ, поддерживаемую локализацию, необходимые варианты, состояние перевода и результат проверки во время выполнения. Рассматривайте каждую комбинацию «пакет — таблица — ключ» как отдельную идентичность сообщения, чтобы одинаковый текст ключа в разных ресурсах не скрывал пропуск.

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

Посмотрите поддерживаемые локализации проекта в редакторе проекта: выберите проект в разделе Project, откройте Info и найдите Localizations. Также проверьте, какие ресурсы входят в эти локализации. В статье Apple Добавление поддержки языков и регионов описаны эти настройки проекта и выбор ресурсов.

В рабочей таблице можно использовать условные обозначения, например «Локализация A», «Локализация B» и «Локализация C». Сохраните соответствие этих обозначений фактическим идентификаторам локализаций проекта в своих рабочих записях. Это метки для таблицы, а не значения, которые нужно вводить в Xcode.

Для проверки используйте следующий критерий завершённости. Это предлагаемый метод ревью, а не статус завершения, определённый Apple.

Проверка Фиксируемые данные
Инвентаризация Для сообщения указаны цель, пакет, таблица и ключ.
Обнаружение Сообщение извлечено из кода или намеренно поддерживается вручную.
Охват Для каждой требуемой локализации предусмотрены необходимые варианты сообщения.
Аргументы Каждый аргумент сохраняет предполагаемый смысл и совместимый тип.
Во время выполнения В соответствующем интерфейсе Mac отображаются правильное сообщение и значения.
Итог Каждая проблема исправлена, исключена с объяснением или остаётся открытой.

Составьте перечень каталога до проверки переводов

Откройте существующие каталоги строк проекта. Если у цели нет каталога, Apple предлагает создать его через File > New > File from Template, а затем выбрать String Catalog. Стандартное имя — Localizable; используйте имя таблицы, которое ожидает ваш код. Выберите Product > Build, чтобы заполнить каталог и обновить его. См. Локализация и варьирование текста с помощью каталога строк.

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

Проверьте параметр сборки Use Compiler to Extract Swift Strings. Apple прямо указывает, что для включения всего локализуемого текста Swift в экспорт локализаций этот параметр должен быть включён. Если для работы над переводом нужна копия для обмена, выберите проект, затем Product > Export Localizations и нужные локализации. Экспортированный пакет .xcloc — это каталог локализации Xcode, отличающийся от отдельной таблицы строк .xcstrings. См. Экспорт локализаций.

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

Не считайте, что извлечение обнаруживает любые произвольные строковые выражения. Apple описывает извлечение через локализуемые API. Если ожидаемого сообщения нет, проверьте, как код создаёт и передаёт его, прежде чем вручную добавлять ещё одну запись. См. Подготовка текста приложения к переводу.

Разделяйте извлечение, поиск и форматирование во время выполнения

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

В SwiftUI важны типы аргументов. Литерал вроде Text("Open collection") участвует в локализованном поиске. Передача обычной переменной типа String в соответствующий инициализатор, как правило, отображает её значение без локализации. Apple описывает это различие в документации LocalizedStringKey.

Явное создание LocalizedStringKey из переменной запрашивает поиск локализованного текста, но это не доказывает, что извлечение во время сборки обнаружило все возможные значения переменной. Для динамически выбираемых ключей сравните полный набор допустимых ключей с каталогом. Разберитесь с каждым несовпавшим значением, а не полагайтесь на значение, которое случайно попалось во время теста.

Интерполяция также задаёт структуру сообщения. SwiftUI может найти локализованное сообщение с заполнителем формата и подставить интерполированное значение перед отображением. Apple рекомендует использовать интерполяцию для составления локализуемого текста в документации Text.

Рассмотрим пример сообщения, которое показывает количество элементов. В каталоге хранится локализуемая структура сообщения и её варианты; меняющееся количество относится к поведению во время выполнения. При проверке значений 1 и 24 не должны требоваться два отдельно поддерживаемых ключа только потому, что изменилось число.

Подпись, которая выглядит правдоподобно, — слабое доказательство успешного поиска. Apple указывает, что SwiftUI может отображать сам ключ, если не находит локализованное значение. Если ключ содержит понятный текст, проблема поиска может выглядеть как обычная подпись. Сверьте выбранную локализацию и запись в каталоге с отображаемым результатом. См. Подготовка представлений к локализации.

Проверьте каждый язык и каждый необходимый вариант

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

В процессе работы с каталогом Apple различает состояния New, Needs Review, переведённые записи и строки Stale. Устаревшая строка больше не найдена в коде; записи, поддерживаемые вручную, автоматически не обновляются и не удаляются при синхронизации. Прежде чем удалять переводы устаревшего ключа, убедитесь, что он не нужен. См. Обнаружение каталогов строк.

Для сообщений, зависящих от количества, щёлкните интерполированный ключ, удерживая Control, и выберите Vary by Plural. Проверьте все формы, предлагаемые Xcode для каждой локализации. Необходимые формы могут различаться, поэтому совпадение количества строк с исходной локализацией не является достаточной проверкой. Если в каталоге есть варианты для устройств, проверьте значение для Mac и общее значение. Apple описывает оба элемента управления в статье Локализация и варьирование текста с помощью каталога строк.

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

Добавляйте контекст, если короткая подпись неоднозначна. Комментарий к Open может пояснять, что это действие для строки коллекции. Параметр SwiftUI comment передаёт этот контекст в данные локализации; Apple описывает его в статье Подготовка представлений к локализации.

Используйте матрицу охвата, которая показывает незавершённую работу

Единый процент полезен для отслеживания хода заполнения каталога, но для проверки нужны отдельные столбцы охвата и поведения. Следующий пример показывает почему. Числа условные и обозначают пары «сообщение — локализация», а не измерения реального приложения.

Предположим, в перечне 48 обязательных сообщений и три поддерживаемые локализации. Всего получается 144 обязательные пары: 48 умножить на 3. В каждой паре могут быть дополнительные варианты для множественного числа или устройств, которые нужно проверить отдельно.

Локализация Обязательные пары Проверки каталога завершены Проверки во время выполнения завершены
Локализация A 48 48 48
Локализация B 48 46 44
Локализация C 48 48 45
Всего 144 142 137

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

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

Запустите приложение Mac для каждой поддерживаемой локализации

Для повторяемых проверок на уровне приложения используйте настройки схемы Xcode. Выберите Product > Scheme > Edit Scheme, затем Run, откройте Options и задайте App Language и App Region. Закройте диалоговое окно, выберите устройство запуска Mac и запустите приложение. Повторите шаги для поддерживаемых сочетаний из вашей проверки. Apple описывает эту последовательность в статье Тестирование локализаций при запуске приложения.

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

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

Предварительный просмотр SwiftUI может ускорить цикл исправлений. Apple позволяет задавать значение окружения locale для предварительного просмотра и создавать несколько локализованных вариантов после добавления или импорта локализаций. Используйте их, чтобы повторно проверить проблемное представление, а затем убедитесь в результате на реальном пути в приложении. См. Предварительный просмотр локализаций.

Завершите проверку, когда для каждой обязательной пары «сообщение — локализация» зафиксирован итог и проверены необходимые ветви. Храните перечень, маршрут тестирования и нерешённые проблемы вместе. Тогда следующая проверка будет практичной: для изменённого сообщения будут известны его расположение, ожидаемые аргументы, необходимые варианты и повторяемый способ проверить отображение.

Источники