Чтобы переименовать ключ каталога строк в Xcode, отдельно сохраните исходное сообщение, обновите ссылки на него в коде и проверьте все существующие переводы и варианты. Для извлечённых строк в Xcode 26 доступен рефакторинг преобразования; простого изменения ключа поиска недостаточно.

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

Что должно остаться неизменным при смене ключа?

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

Перед редактированием зафиксируйте следующие данные для каждой затронутой записи. Эти условные примеры иллюстрируют переименование и не являются результатами измерений.

Компонент До Ожидаемый результат
Ключ поиска Open collection collection.open
Исходное сообщение Open collection Без изменений
Таблица Localizable Без изменений
Пакет Пакет основного приложения Без изменений
Контекст для переводчика Кнопка, открывающая выбранную коллекцию Сохранён
Существующие переводы Текущие значения для каждой локализации Сохранены
Аргументы количества, если есть Целое число Тот же тип и смысл
Варианты множественного числа или устройства Существующие ветви Сохранены

Используйте эту запись для сравнения. Успешная сборка сама по себе не доказывает, что переводы сохранились: приложение всё ещё может показывать текст по умолчанию, если поиск не дал результата. В документации SwiftUI сказано, что локализованный ключ может отображаться напрямую, если совпадение в каталоге не найдено. При семантическом ключе это может привести к тому, что в интерфейсе появится идентификатор, например collection.open. Подготовка представлений к локализации

Найдите исходный текст до редактирования каталога

Откройте существующий каталог в навигаторе проекта Xcode. Выберите Editor > Assistant, затем выберите запись, чтобы просмотреть её источник. Apple также описывает стрелку рядом с ключом и примеры использования в инспекторе атрибутов как способы найти ссылки. Для извлечённых строк после изменений в исходном коде выберите Product > Build, чтобы синхронизировать каталог. Локализация и варьирование текста с помощью каталога строк

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

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

Используйте рефакторинг преобразования Xcode для извлечённых строк

Если проект использует Xcode 26 или новее, рассмотрите возможность преобразовать существующую извлечённую запись в сгенерированный локализуемый символ. Apple представила этот процесс в Xcode 26 и показывает, как при преобразовании изменить ключ на содержательное имя. Это документированный способ одновременно изменить способ идентификации сообщения и ссылки на него. Практическое занятие: знакомство с локализацией в Xcode

  1. В настройках сборки проверьте, включён ли параметр Generate String Catalog Symbols (Yes), если для существующего проекта его нужно активировать.
  2. В редакторе каталога выберите существующий ключ, щёлкните по нему, удерживая Control, и выберите Refactor > Convert Strings to Symbols.
  3. Просмотрите предварительный просмотр изменений ключа каталога и затронутых мест в исходном коде.
  4. В интерфейсе преобразования отредактируйте предлагаемое содержательное имя и, если применимо, имена аргументов.
  5. Сравните текущий и изменённый код в подсвеченном предварительном просмотре, затем нажмите Convert.
  6. Выполните сборку и сравните полученную запись с контрольной точкой, включая переводы и варианты.

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

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

Сохраните извлечение, если хотите задавать ключи и значения по умолчанию в коде

Можно также оставить извлечение под управлением кода. Apple явно поддерживает отдельные ключи поиска и исходные сообщения с помощью String(localized:defaultValue:...): первый аргумент задаёт ключ, а defaultValue — исходную строку. Например, для семантического ключа можно оставить Open collection текстом по умолчанию. Подготовка текста приложения к переводу

Ниже приведён полный пример исходного кода приложения с одной статической подписью и одним целочисленным значением количества. Используйте целевой объект приложения macOS на SwiftUI с целевой версией macOS 12 или новее и замените исходный код существующей точки входа приложения, а не добавляйте второе объявление @main. Добавьте Localizable.xcstrings в целевой объект приложения. Пример сверен с API Apple; здесь он не компилировался, поскольку среда инструментов Swift была недоступна.

import Foundation
import SwiftUI

@main
struct CatalogRenameDemoApp: App {
    var body: some Scene {
        WindowGroup {
            CatalogRenameDemoView()
        }
    }
}

struct CatalogRenameDemoView: View {
    private let itemCount: Int = 7

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(verbatim: String(
                localized: "collection.open",
                defaultValue: "Open collection",
                comment: "Label for opening the selected collection."
            ))

            Text(verbatim: String(
                localized: "collection.itemCount",
                defaultValue: "\(itemCount) items",
                comment: "Number of items in the selected collection."
            ))
        }
        .padding()
    }
}

Здесь String(localized:...) разрешает локализованный текст до того, как полученная строка отображается. Text(verbatim:) явно указывает этот шаг отображения. Apple различает немедленную локализацию строки и LocalizedStringResource, представляющий поиск, который можно отложить. Для повторно используемых интерфейсов, где между представлениями передаются неразрешённые сообщения, Apple рекомендует локализуемый тип, например LocalizedStringResource. LocalizedStringResource, Подготовка текста приложения к переводу

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

Чем извлечение отличается от форматирования во время выполнения?

Извлечение выполняется во время разработки: Xcode обнаруживает поддерживаемые локализуемые выражения и обновляет каталог. Форматирование во время выполнения происходит, когда приложение разрешает сообщение и вставляет значения. В примере счётчик 7 — аргумент времени выполнения; он не должен становиться частью постоянного ключа.

Оставляйте интерполяцию целого числа внутри локализуемого выражения. String.LocalizationValue в API Apple поддерживает интерполяцию и для тех, кому нужны произвольные идентификаторы, указывает на инициализаторы со статическим ключом и отдельным defaultValue. Сначала сформировать обычную отображаемую строку — не то же самое, что сохранить локализуемое сообщение и его аргументы. String.LocalizationValue

Для сообщений о количестве с грамматическими формами выберите извлечённую запись с количеством, щёлкните по ней, удерживая Control, и выберите Vary by Plural. Заполните варианты для исходного языка и все обязательные варианты существующих локализаций. Для английского исходного языка Apple приводит варианты One с %lld item и Other с %lld items. Одной интерполяции недостаточно, чтобы завершить работу с этими вариантами. Локализация и варьирование текста с помощью каталога строк

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

Проверьте сохранность данных, прежде чем удалять старую запись

Используйте следующие проверки как критерии завершения. Они помогают отличить проблему каталога от проблемы поиска или форматирования.

Проверка Ожидаемый результат Что проверить при сбое
Исходный текст Совпадает с контрольной точкой Отсутствует или изменено значение по умолчанию
Существующие переводы Все прежние значения доступны по новому ключу Перенос завершён не полностью или выбран неверный адрес назначения
Структура вариантов Сохранены все прежние варианты множественного числа и устройства Скопировано только значение верхнего уровня
Подпись в приложении Отображается нужное сообщение Несовпадение ключа, таблицы, пакета или локализации
Условные значения счётчика 0, 1, 7 Значения вставляются правильно и необходимые ветви множественного числа работают Несовпадение аргумента или варианта
Старые ссылки Нет ссылок, которые необходимо сохранить Перенос выполнен не полностью

Чтобы проверить приложение для Mac в существующей локализации, выберите Product > Scheme > Edit Scheme, пункт Run, откройте Options и выберите App Language. Закройте диалоговое окно и запустите целевой объект Mac. Повторите проверку для локализаций, затронутых переименованием, просматривая настоящую подпись и сообщение со счётчиком. Apple документирует этот способ проверки с помощью схемы. Проверка локализаций при запуске приложения

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

Источники