En Xcode 26 y versiones posteriores, los catálogos de cadenas pueden generar accesores Swift que reemplazan las claves de localización escritas manualmente. En esta guía, se migra el resumen de selección de una pequeña app para Mac a propiedades y funciones con tipos definidos y, después, se comprueba qué protege realmente el compilador.

La tarea tiene un alcance deliberadamente reducido: mostrar el encabezado de una ventana y un resumen con dos recuentos de enteros. Todas las etiquetas y los valores son sintéticos. Crearás el contrato del catálogo, lo conectarás con SwiftUI y verificarás tanto los diagnósticos del compilador como el resultado visible.

¿Qué hace que un accesor de localización tenga comprobación de tipos en tiempo de compilación?

Apple introdujo la generación nativa de símbolos de catálogos de cadenas en Xcode 26. Una entrada sin marcadores de posición genera una propiedad estática; una entrada con marcadores de posición genera una función con parámetros tipados. Ambas devuelven LocalizedStringResource. Los proyectos nuevos de Xcode 26 habilitan la generación de forma predeterminada; en los proyectos existentes puede ser necesario activar el ajuste de compilación. Tutorial: Explora la localización con Xcode

El cambio útil se produce en el punto de llamada. Un literal de cadena puede escribir una clave de búsqueda sin hacer referencia a una declaración de Swift. Un accesor generado hace referencia a un miembro que debe existir, y una función generada exige argumentos que coincidan con su firma. De esos mecanismos documentados se desprende una consecuencia práctica: un miembro mal escrito o un argumento incompatible genera un error del compilador.

Esa protección tiene un alcance concreto. Swift puede comprobar que el accesor existe y que sus argumentos son compatibles. No puede determinar si el texto describe la interfaz prevista ni si dos argumentos enteros válidos representan los recuentos correctos. Considera los accesores una interfaz de programación con comprobación de tipos para tus mensajes.

Configura una pequeña app para Mac y el contrato de sus mensajes

Usa Xcode 26 o posterior y un destino de app SwiftUI para macOS. En este ejemplo, establece como destino de implementación macOS 15 o posterior. El tipo LocalizedStringResource subyacente está disponible desde macOS 13; el destino superior del ejemplo es un requisito elegido para este caso, no la versión mínima de ese tipo. Un recurso representa texto localizable cuya búsqueda puede posponerse hasta que se necesite. LocalizedStringResource

Añade un catálogo mediante File > New > File from Template. Selecciona String Catalog en Resource, llámalo Workbench e inclúyelo en el destino de la app. Apple documenta que cada catálogo representa una tabla; aquí se usa una tabla aparte para mantener juntos los dos mensajes del ejemplo. Localizar y adaptar texto con un catálogo de cadenas

En el editor del proyecto, abre Build Settings, filtra por Generate String y establece Generate String Catalog Symbols en Yes para la configuración efectiva del destino. Este es el ajuste documentado para proyectos anteriores. Usar en el código símbolos localizables generados

Selecciona la localización de origen en inglés en Workbench.xcstrings. Añade estas dos entradas con el botón + de la barra de herramientas del editor del catálogo. Los comentarios definen el significado de los mensajes, incluidos los roles de sus argumentos.

Clave Valor de origen en inglés Comentario
TITLE Selection overview Heading above the selection summary.
SUBTITLE %1$(selectedCount)lld selected; %2$(availableCount)lld available Selection summary. selectedCount is the number selected; availableCount is the total number available, including selected items.

Para SUBTITLE, puedes introducir cada marcador de posición mediante el menú de autocompletado de Xcode: escribe %, elige el marcador de posición entero y asígnale el nombre selectedCount o availableCount. Apple documenta las variables con nombre y los parámetros generados para estos especificadores de formato. Selecciona cada entrada y examina Generate Swift Symbol y Example Usages en el inspector de atributos. Usar en el código símbolos localizables generados

El contrato previsto es una propiedad para el título y una función para el subtítulo que acepte dos valores Int. Antes de continuar, comprueba en el inspector la grafía generada real: Apple indica que los nombres de los símbolos usan tanto la clave como su valor. Los ejemplos siguientes usan .Workbench.title y .Workbench.subtitle(selectedCount:availableCount:), siguiendo el patrón documentado por Apple para claves en mayúsculas. Tutorial: Explora la localización con Xcode

Este contrato hace explícita una distinción útil: availableCount incluye los elementos seleccionados. Sin ese comentario, quien hiciera la llamada podría interpretarlo razonablemente como el número de elementos restantes. Ambas interpretaciones superarían la comprobación de tipos, así que documentar el significado es parte de hacer útil el accesor.

Usa los accesores generados en una ventana completa

Después de crear el catálogo, elige Product > Build. Reemplaza la declaración de la app de plantilla y la vista de contenido por el siguiente programa; asegúrate de que haya exactamente una declaración @main en el destino. Este programa requiere el catálogo como recurso; pegar el código Swift en un archivo independiente no genera sus accesores.

import Foundation
import SwiftUI

@main
struct SelectionOverviewApp: App {
    var body: some Scene {
        WindowGroup {
            SelectionOverviewView(
                selectedCount: 3,
                availableCount: 12
            )
        }
    }
}

struct SelectionOverviewView: View {
    let selectedCount: Int
    let availableCount: Int

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(.Workbench.title)
                .font(.title2)

            Text(
                .Workbench.subtitle(
                    selectedCount: selectedCount,
                    availableCount: availableCount
                )
            )
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 140)
    }
}

Con la localización de origen en inglés activa, las entradas ilustrativas deberían mostrar Selection overview seguido de 3 selected; 12 available. Los recuentos son fijos para que puedas comprobar la posición de los argumentos sin añadir código para administrar la selección.

Apple documenta que los recursos generados pueden usarse en SwiftUI, incluido Text, y mediante el inicializador String(localized:) de Foundation. Si una interfaz existente para Mac necesita un String resuelto, convierte el recurso generado en ese límite. Tutorial: Explora la localización con Xcode

Por ejemplo, esta es una función auxiliar completa que puedes añadir al mismo destino de la app una vez que exista el catálogo:

import Foundation

func selectionSummary(
    selectedCount: Int,
    availableCount: Int
) -> String {
    String(
        localized: .Workbench.subtitle(
            selectedCount: selectedCount,
            availableCount: availableCount
        )
    )
}

Devolver LocalizedStringResource desde tu propia interfaz conserva un recurso para realizar la búsqueda más adelante; devolver String lo resuelve cuando se ejecuta el inicializador. Elige según las necesidades de la interfaz receptora. Apple describe esta distinción entre búsqueda diferida e inmediata en la documentación de Foundation. LocalizedStringResource

Los ejemplos se contrastaron con la documentación consultada. No se compilaron aquí porque el entorno disponible no cuenta con Swift ni Xcode.

Por qué importan el punto inicial y las etiquetas de los argumentos

El punto inicial es la sintaxis de miembro implícito de Swift. Abrevia el acceso a un miembro de tipo cuando el contexto permite a Swift inferir el tipo. Es sintaxis normal de Swift, no un operador especial para claves de cadena. Expresiones — Expresión de miembro implícito

En los símbolos de localización generados, la tabla predeterminada Localizable expone los miembros directamente, mientras que una tabla con nombre introduce un espacio de nombres de tabla. Por eso, este ejemplo incluye .Workbench antes del nombre del miembro. Apple documenta ambas formas. Usar en el código símbolos localizables generados

Las etiquetas selectedCount: y availableCount: pertenecen a la llamada a la función. Swift distingue las etiquetas de argumentos, que aparecen en el punto de llamada, de los nombres de parámetros que se usan dentro de una función. Cuando un parámetro requiere una etiqueta, quien llama debe proporcionarla. Funciones — Etiquetas de argumentos y nombres de parámetros de funciones

Las etiquetas descriptivas ayudan a evitar errores, pero en este caso ambos argumentos tienen el mismo tipo. Intercambiar los dos valores enteros sigue siendo válido en Swift. Por eso, el contrato del mensaje y la comprobación del resultado visible complementan al compilador.

Migra las claves existentes sin perder su significado

Para las cadenas localizables existentes, Apple ofrece un flujo de refactorización. Selecciona entradas en el catálogo de cadenas, haz clic con la tecla Control y elige Refactor > Convert Strings to Symbols. Examina la vista previa, ajusta los nombres propuestos para los símbolos o los parámetros si hace falta y elige Convert. Usar en el código símbolos localizables generados

Migra primero un grupo coherente, como el encabezado y el resumen de esta ventana. Antes de aceptar la vista previa, compara el mensaje anterior con el nuevo contrato: ¿usan la misma tabla?, ¿describen el mismo elemento de la interfaz?, ¿asignan el mismo significado a cada marcador de posición? Revisa los valores localizados existentes afectados por un cambio de clave en vez de dar por sentado que la refactorización demuestra que son correctos.

Para los puntos de llamada que la refactorización no actualice, consulta el uso generado en el inspector del catálogo y reemplaza esa referencia explícitamente. Después, compila e inspecciona el texto resultante. No elimines la entrada anterior hasta haber identificado todos sus puntos de llamada.

Si la versión instalada de Xcode no incluye generación nativa, este flujo requiere una cadena de herramientas más reciente. Apple también admite extraer cadenas de las API localizables a catálogos y recomienda la extracción como punto de partida. Sigue siendo una forma admitida de gestionar la localización, pero por sí sola no proporciona el contrato de accesores generados que se describe aquí. Tutorial: Explora la localización con Xcode

Verifica la migración con una breve secuencia de diagnóstico

Usa las siguientes comprobaciones con la ventana de ejemplo. Permiten distinguir la protección del compilador de la corrección del mensaje y la integración del recurso.

  1. Compila el ejemplo sin cambios para establecer una base funcional.
  2. Escribe temporalmente de forma incorrecta el nombre del miembro del título y compila. El miembro inexistente debería generar un diagnóstico del compilador. Restáuralo.
  3. Pasa temporalmente un valor String donde el subtítulo requiere un Int. Compila para comprobar el error de tipos y luego vuelve a poner el entero.
  4. Ejecuta con selectedCount establecido en 3 y availableCount establecido en 12. Confirma que los números aparecen en las posiciones previstas.
  5. Cambia solo el valor del título en el catálogo a Current selection, vuelve a compilar y confirma el encabezado mostrado. Comprueba que la firma generada siga siendo la que usa tu código.

Si falta inesperadamente un miembro, consulta primero el uso generado de la entrada del catálogo. Después, comprueba el ajuste de generación, la pertenencia del catálogo al destino y el nombre de la tabla. Un diagnóstico del compilador identifica una referencia fallida; estas comprobaciones ayudan a distinguir un error de escritura de una declaración generada que no está disponible.

Por último, prueba la interfaz real. El procedimiento documentado por Apple es abrir Product > Scheme > Edit Scheme y luego Run > Options, donde puedes seleccionar App Language antes de ejecutar. Repite el proceso para las localizaciones que admita tu proyecto. Probar localizaciones al ejecutar la app

Para comprobar pronto el diseño, Xcode también ofrece Double-Length Pseudolanguage, que amplía el texto localizable para revelar problemas de tamaño. Inspecciona el resumen con una ventana estrecha; compilar correctamente no permite determinar si el texto cabe. Probar localizaciones

Una migración completa ofrece a cada punto de llamada un miembro Swift real, asigna un rol documentado a cada variable y conserva una ruta comprobable hasta la entrada correspondiente del catálogo. Mantén juntas las comprobaciones del compilador y de la ventana: las primeras validan el contrato del accesor y las segundas confirman que el lector ve el mensaje previsto.

Fuentes