Para cambiar el nombre de una clave del catálogo de cadenas en Xcode, conserva el mensaje de origen por separado, actualiza las referencias en el código y verifica todas las traducciones y variantes existentes. Para las cadenas extraídas, Xcode 26 ofrece una refactorización de conversión; cambiar solo la clave de búsqueda no es suficiente.

Esta guía está dirigida a quien mantiene una app para Mac en SwiftUI con un catálogo .xcstrings existente. La tarea consiste en reemplazar las claves que son frases por identificadores significativos, conservando intactos el texto que se muestra y las traducciones. Apple documenta las API y el flujo de conversión que se describen a continuación, pero no garantiza que una edición arbitraria de una clave transfiera automáticamente todas las traducciones.

¿Qué debe permanecer sin cambios al cambiar una clave?

Un mensaje localizable tiene más elementos que un identificador. Apple describe su clave, valor predeterminado, comentario y tabla de cadenas como componentes independientes. La clave identifica el mensaje en tiempo de ejecución; el valor predeterminado proporciona el texto de origen. Un catálogo contiene las traducciones y los metadatos de una tabla. Trata el cambio de nombre como una modificación coordinada del contrato de ese mensaje. Descubrir los catálogos de cadenas

Antes de editar, registra lo siguiente para cada entrada afectada. Estos ejemplos sintéticos ilustran un cambio de nombre; no son resultados medidos.

Componente Antes Resultado previsto
Clave de búsqueda Open collection collection.open
Mensaje de origen Open collection Sin cambios
Tabla Localizable Sin cambios
Paquete Paquete principal de la app Sin cambios
Contexto para traductores Botón que abre la colección seleccionada Se conserva
Traducciones existentes Valores actuales en cada idioma Se conservan
Argumentos de recuento, si los hay Recuento entero Mismo tipo y significado
Variantes plurales o por dispositivo Ramas existentes Se conservan

Usa este registro para facilitar la comparación. Una compilación correcta por sí sola no demuestra que se hayan conservado las traducciones: la app aún podría mostrar un mensaje predeterminado cuando no encuentra la clave. SwiftUI documenta que una clave localizable puede mostrarse directamente si no hay ninguna coincidencia en el catálogo. Con una clave semántica, eso puede hacer que en la interfaz aparezca un identificador como collection.open. Preparar las vistas para la localización

Encuentra el origen antes de editar el catálogo

Abre el catálogo existente en el navegador de proyectos de Xcode. Elige Editor > Assistant y selecciona la entrada para inspeccionar su origen. Apple también documenta como métodos para localizar las referencias la flecha junto a una clave y los usos de ejemplo en el inspector de atributos. Para las cadenas extraídas, elige Product > Build después de cambiar el código fuente para sincronizar el catálogo. Localizar y variar el texto con un catálogo de cadenas

Comprueba si la entrada se extrae del código o se administra manualmente. Apple explica que el código fuente controla los mensajes extraídos: las compilaciones sincronizan sus valores de origen. Una entrada traducida que deja de extraerse permanece como Stale; una que no está traducida puede eliminarse. Las entradas administradas manualmente no se actualizan ni se eliminan durante la extracción. Por lo tanto, no elimines una entrada traducida antigua solo porque haya aparecido un reemplazo. Descubrir los catálogos de cadenas

Crea un punto de control recuperable antes de continuar y compara con él la entrada afectada después. Mantén sin cambios la tabla y el paquete durante esta tarea para reducir las posibles causas de una traducción ausente. Las API de localización de Apple aceptan la información de la tabla y el paquete precisamente porque determinan dónde se encuentra un mensaje. Preparar el texto de tu app para la traducción

Usa la refactorización de conversión de Xcode para las cadenas extraídas

Si el proyecto usa Xcode 26 o posterior, considera convertir la entrada extraída existente en un símbolo localizable generado. Apple presentó este flujo de trabajo en Xcode 26 y muestra cómo cambiar una clave por un nombre semántico durante la conversión. Es un método documentado para cambiar conjuntamente la forma de identificar y referenciar un mensaje. Tutorial práctico: Explorar la localización con Xcode

  1. En los ajustes de compilación, comprueba que Generate String Catalog Symbols esté configurado como Yes si el proyecto actual necesita habilitarlo.
  2. En el editor del catálogo, selecciona la clave existente, haz clic con Control y elige Refactor > Convert Strings to Symbols.
  3. Inspecciona la vista previa, que muestra el cambio de clave en el catálogo y las ubicaciones de código afectadas.
  4. Edita el nombre semántico propuesto y, cuando corresponda, los nombres de los argumentos en la interfaz de conversión.
  5. Compara el código actual y el modificado en la vista previa resaltada y, a continuación, haz clic en Convert.
  6. Compila y compara la entrada resultante con el punto de control, incluidas las traducciones y variantes.

Apple documenta estos controles de conversión y muestra ejemplos de uso generado en el inspector de atributos. Usa esos ejemplos en lugar de adivinar un identificador de Swift a partir de la puntuación de la clave deseada del catálogo. Los símbolos generados dependen de la información del catálogo y las tablas distintas de la predeterminada incluyen un espacio de nombres para la tabla. Usar en el código los símbolos localizables generados

Esta refactorización está pensada específicamente para pasar de cadenas extraídas a símbolos generados. La documentación citada no establece una operación universal de cambio de nombre para todas las entradas administradas manualmente ni para todas las referencias externas. Si la vista previa omite una referencia necesaria, tenla en cuenta explícitamente antes de eliminar la clave anterior.

Conserva la extracción si prefieres definir las claves y los valores predeterminados en el código

También puedes conservar la extracción controlada por el código. Apple admite explícitamente claves de búsqueda y mensajes de origen separados mediante String(localized:defaultValue:...): el primer argumento proporciona la clave y defaultValue proporciona la cadena de origen. Por ejemplo, una clave semántica puede conservar Open collection como mensaje predeterminado. Preparar el texto de tu app para la traducción

El siguiente código fuente completo de una app muestra ese patrón con una etiqueta estática y un recuento entero. Usa un objetivo de app SwiftUI para macOS con un destino de implementación de macOS 12 o posterior y reemplaza el archivo de origen de la entrada existente de la app en lugar de añadir una segunda declaración @main. Añade Localizable.xcstrings al objetivo de la app. El ejemplo se revisó con respecto a las API de Apple; no se compiló aquí porque no había disponible una cadena de herramientas de 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()
    }
}

Aquí, String(localized:...) resuelve el texto localizado antes de mostrar la cadena resultante. Text(verbatim:) hace explícito ese paso de visualización. Apple distingue la localización inmediata de cadenas de LocalizedStringResource, que representa una búsqueda que puede aplazarse. Para interfaces reutilizables que pasan mensajes sin resolver entre vistas, Apple recomienda un tipo localizable como LocalizedStringResource. LocalizedStringResource, Preparar el texto de tu app para la traducción

Al migrar un mensaje existente con este método, compila para crear o actualizar la entrada de destino y luego transfiere las traducciones existentes antes de eliminar la entrada anterior. Apple documenta cómo introducir traducciones directamente: se selecciona un idioma y se edita la columna correspondiente. En un mensaje con variantes, conserva cada rama pertinente en lugar de copiar solo el texto de nivel superior. Esta transferencia por etapas es un procedimiento práctico de migración derivado de las herramientas de edición documentadas, no una garantía de cambio de nombre automático. Localizar y variar el texto con un catálogo de cadenas

¿En qué se diferencian la extracción y el formato en tiempo de ejecución?

La extracción ocurre durante el desarrollo: Xcode detecta las expresiones localizables admitidas y actualiza el catálogo. El formato en tiempo de ejecución ocurre cuando la app resuelve el mensaje e inserta valores. El ejemplo de recuento 7 es un argumento de tiempo de ejecución; no debería formar parte de la clave estable.

Mantén la interpolación del entero dentro de la expresión localizable. String.LocalizationValue de Apple admite la interpolación y, para quienes quieran identificadores arbitrarios, remite a inicializadores con una clave estática y un defaultValue separado. Crear primero una cadena normal ya formateada no equivale a conservar ese mensaje localizable y sus argumentos. String.LocalizationValue

Para los mensajes de recuento con reglas gramaticales, selecciona la entrada de recuento extraída, haz clic con Control y elige Vary by Plural. Completa las variantes de origen y las variantes necesarias en cada idioma existente. Para un texto de origen en inglés, Apple muestra One con %lld item y Other con %lld items. Añadir interpolación por sí sola no completa esas variantes. Localizar y variar el texto con un catálogo de cadenas

Durante un cambio de nombre, conserva los tipos, las posiciones y los significados de los argumentos. Si el mensaje anterior contiene un recuento entero, reemplazarlo por una cadena preformateada también cambia el contrato de formato. Para los símbolos generados, Xcode crea funciones con parámetros tipados para los mensajes que contienen especificadores de formato; inspecciona esas firmas al convertir. Usar en el código los símbolos localizables generados

Verifica que se haya conservado el contenido antes de eliminar la entrada anterior

Usa las siguientes comprobaciones para determinar si la tarea está completa. Permiten distinguir un problema del catálogo de uno de búsqueda o formato.

Comprobación Resultado esperado Investiga si falla
Texto de origen Coincide con el punto de control Falta el valor predeterminado o se ha alterado
Traducciones existentes Todos los valores anteriores siguen disponibles con la clave nueva Transferencia incompleta o destino incorrecto
Estructura de variantes Se conservan todas las ramas plurales y por dispositivo anteriores Solo se copió un valor de nivel superior
Etiqueta en tiempo de ejecución Muestra el mensaje previsto Discrepancia en la clave, tabla, paquete o idioma
Recuentos sintéticos 0, 1, 7 Los valores se insertan correctamente y funcionan las ramas plurales necesarias Discrepancia en los argumentos o las variantes
Referencias anteriores No quedan usos necesarios Migración incompleta

Para probar la app para Mac en un idioma existente, elige Product > Scheme > Edit Scheme, selecciona Run, abre Options y elige un App Language. Cierra el cuadro de diálogo y ejecuta el destino para Mac. Repite el proceso con los idiomas afectados por el cambio de nombre y comprueba la etiqueta y el mensaje de recuento reales. Apple documenta este flujo de prueba mediante el esquema. Probar las localizaciones al ejecutar la app

Si aparece la clave nueva, pero su traducción está vacía, vuelve a la entrada anterior y transfiere el contenido que falta. Si el identificador aparece en pantalla, inspecciona los parámetros de búsqueda. Si solo fallan los recuentos, inspecciona la interpolación y las variantes. Elimina la entrada anterior cuando hayas tenido en cuenta su contenido y trasladado las referencias necesarias. El cambio final debería modificar el identificador y conservar el mensaje, sus argumentos y las traducciones que ya reciben los lectores.

Fuentes