Para auditar cada clave de localización en una app de Mac, compile los objetivos relevantes, verifique cada tabla de cadenas con cada idioma admitido y, a continuación, pruebe las variantes de mensaje en la app en ejecución. La finalización del catálogo y la visualización correcta en tiempo de ejecución requieren comprobaciones independientes.

Este flujo de trabajo está destinado a un desarrollador que mantiene una app de escritorio de Mac en Xcode. Su tarea concreta es producir un registro rastreable de mensajes faltantes, traducciones incompletas, argumentos incorrectos y problemas de visualización. Los ejemplos usan etiquetas y conteos sintéticos; describen un método de auditoría que puede aplicar a su propio proyecto.

Definir qué cuenta como un mensaje completo

Comience con una hoja de trabajo de auditoría pequeña. Registre el objetivo de la app, el paquete de recursos, la tabla de cadenas, la clave, la localización admitida, las variantes requeridas, el estado de la traducción y el resultado en tiempo de ejecución. Trate cada combinación paquete-tabla-clave como una identidad de mensaje separada para que un texto de clave idéntico en diferentes recursos no oculte una omisión.

Apple documenta que las API localizables pueden especificar una tabla y un paquete, y que los recursos fuera del paquete principal necesitan el paquete apropiado para la búsqueda. Por lo tanto, comprobar solo el archivo Localizable.xcstrings predeterminado puede pasar por alto mensajes en otras partes de la app. Consulte Preparar el texto de su app para la traducción.

Lea las localizaciones admitidas del proyecto en el editor de proyectos: seleccione el proyecto en Project, abra Info e inspeccione Localizations. También inspeccione qué recursos participan en esas localizaciones. Agregar compatibilidad con idiomas y regiones de Apple explica estos ajustes y selecciones de recursos del proyecto.

Para la hoja de trabajo, puede usar alias sintéticos como Localización A, Localización B y Localización C. Mantenga su asignación a los identificadores de localización reales del proyecto en su registro de trabajo. Estos alias son etiquetas de la hoja de trabajo, no valores para ingresar en Xcode.

Utilice el siguiente contrato de finalización para la auditoría. Este es un método de revisión propuesto, no un estado de finalización definido por Apple.

Comprobación Evidencia a registrar
Inventario El mensaje tiene un objetivo, paquete, tabla y clave identificados.
Detección El mensaje se extrae del código o se mantiene deliberadamente de forma manual.
Cobertura Cada localización requerida tiene las variantes de mensaje necesarias.
Argumentos Cada argumento conserva su significado previsto y tipo compatible.
Tiempo de ejecución El mensaje y los valores correctos aparecen en la interfaz de Mac relevante.
Disposición Cada hallazgo se corrige, se excluye deliberadamente con una razón o permanece abierto.

Crear el inventario del catálogo antes de revisar las traducciones

Abra los catálogos de cadenas existentes del proyecto. Si un objetivo no tiene catálogo, la ruta de creación documentada por Apple es File > New > File from Template, luego seleccione String Catalog. El nombre predeterminado es Localizable; use el nombre de tabla que su código espera. Elija Product > Build para poblar y actualizar el catálogo. Consulte Localizar y variar texto con un catálogo de cadenas.

Compile cada esquema de Mac relevante en lugar de tratar una compilación exitosa como el inventario completo. Apple explica que la extracción descubre cadenas para el esquema y la plataforma actuales. Un mensaje ausente en una compilación merece investigación antes de concluir que no se usa. Este límite se describe en Descubrir catálogos de cadenas.

Compruebe el ajuste de compilación Use Compiler to Extract Swift Strings. Apple lo requiere explícitamente para incluir todo el texto de Swift localizable en las exportaciones de localización. Si necesita una copia de intercambio para el trabajo de traducción, seleccione el proyecto y elija Product > Export Localizations, luego elija las localizaciones requeridas. El paquete .xcloc exportado es un Catálogo de localización de Xcode, distinto de una tabla de cadenas .xcstrings individual. Consulte Exportar localizaciones.

A continuación, recorra las superficies de escritorio ordinarias de la app: su ventana principal, menús, barra de herramientas, ajustes, paneles, estados vacíos y etiquetas dependientes del conteo. Para cada mensaje propio de la app que encuentre, localice su entrada en la hoja de trabajo. Esta comprobación inversa (de la interfaz visible al inventario) ayuda a descubrir texto que nunca llegó a un catálogo.

No suponga que la extracción descubre toda expresión de cadena arbitraria. Apple describe la extracción a través de API localizables. Cuando falta un mensaje esperado, inspeccione cómo el código lo crea y lo pasa antes de agregar una segunda entrada manualmente. Consulte Preparar el texto de su app para la traducción.

Separar extracción, búsqueda y formato en tiempo de ejecución

Estas operaciones responden preguntas diferentes. La extracción pregunta si Xcode puede descubrir un mensaje durante el desarrollo. La búsqueda pregunta qué recurso localizado solicita la app en ejecución. El formato en tiempo de ejecución proporciona el contenido variable que muestra el mensaje seleccionado.

En SwiftUI, los tipos de argumentos importan. Un literal como Text("Open collection") participa en la búsqueda localizada. Pasar una variable String simple al inicializador correspondiente normalmente muestra esa variable sin localización. Apple documenta esta distinción en LocalizedStringKey.

Crear explícitamente un LocalizedStringKey desde una variable solicita la búsqueda, pero eso no establece que la extracción en tiempo de compilación descubrió todos los valores posibles de la variable. Para claves seleccionadas dinámicamente, compare el conjunto completo de claves permitidas con el catálogo. Investigue cada valor no coincidente en lugar de confiar en el valor que ocurrió durante una prueba.

La interpolación también tiene un papel a nivel de mensaje. SwiftUI puede buscar un mensaje localizado que contenga un especificador de formato y sustituir el valor interpolado antes de renderizar. Apple recomienda la interpolación para componer texto localizable en la documentación de Text.

Considere un mensaje ilustrativo que informa un conteo de elementos. El catálogo almacena su estructura y variantes de mensaje localizables; el conteo cambiante pertenece al comportamiento en tiempo de ejecución. Probar conteos de 1 y 24 no debería requerir dos claves mantenidas independientemente solo porque el número cambió.

Una etiqueta de aspecto plausible es una evidencia débil de búsqueda exitosa. Apple indica que SwiftUI puede mostrar la clave misma cuando no encuentra el valor localizado. Si una clave es texto de origen legible, un problema de búsqueda puede parecer una etiqueta ordinaria. Verifique la localización seleccionada y la entrada del catálogo junto con el resultado mostrado. Consulte Preparar vistas para la localización.

Revisar cada idioma y cada variante requerida

Trabaje con una tabla a la vez y una localización a la vez. Para cada mensaje, verifique su estado de traducción, texto, argumentos y variaciones expandidas. Mantenga las filas incompletas abiertas incluso cuando los mensajes circundantes estén completos.

El flujo de trabajo del catálogo de Apple distingue New, Needs Review, entradas traducidas y cadenas Stale. Una entrada obsoleta ya no se encontró en el código; las entradas administradas manualmente no se actualizan ni eliminan automáticamente durante la sincronización. Confirme que una clave obsoleta es innecesaria antes de eliminar sus traducciones. Consulte Descubrir catálogos de cadenas.

Para mensajes dependientes del conteo, haga Control-clic en la clave interpolada y elija Vary by Plural. Revise cada formulario que Xcode proporciona para cada localización. Los formularios requeridos pueden diferir, por lo que igualar el conteo de filas de la localización de origen no es una comprobación suficiente. Si el catálogo incluye variaciones de dispositivo, inspeccione el valor específico de Mac y el valor general. Apple documenta ambos controles en Localizar y variar texto con un catálogo de cadenas.

Verifique los argumentos por significado y apariencia. Para un mensaje sintético que informa elementos entre grupos, identifique qué argumento representa el conteo de elementos y cuál el conteo de grupos. Una traducción puede cambiar su ubicación mientras aún necesita preservar esos significados. La sesión del catálogo de Apple explica posiciones de argumentos, especificadores de tipo y sustituciones plurales en Descubrir catálogos de cadenas.

Agregue contexto donde una etiqueta corta sea ambigua. Un comentario para Open podría identificarla como la acción en una fila de colección. El parámetro comment de SwiftUI lleva ese contexto a la salida de localización; Apple lo describe en Preparar vistas para la localización.

Usar una matriz de cobertura que exponga el trabajo incompleto

Un solo porcentaje es útil para rastrear el progreso del catálogo, pero la auditoría necesita columnas separadas para cobertura y comportamiento. El siguiente ejemplo trabajado ilustra por qué. Sus números son sintéticos y representan pares mensaje-localización, no mediciones de una app.

Supongamos que el inventario contiene 48 mensajes requeridos y tres localizaciones admitidas. Eso produce 144 pares requeridos: 48 multiplicado por 3. Cada par puede contener ramas plurales o de dispositivo adicionales, que necesitan sus propias comprobaciones.

Localización Pares requeridos Comprobaciones de catálogo completadas Comprobaciones de tiempo de ejecución completadas
Localización A 48 48 48
Localización B 48 46 44
Localización C 48 48 45
Total 144 142 137

Aquí, dos pares aún necesitan trabajo de catálogo y siete aún carecen de comprobaciones de tiempo de ejecución completadas. Esos grupos pueden superponerse, por lo que sumarlos no produciría un conteo confiable de mensajes incompletos distintos. Mantenga ambos hallazgos adjuntos a sus filas reales.

Para cada fila incompleta, registre una próxima acción específica: localizar un mensaje de origen faltante, completar una rama plural, verificar un argumento, investigar la selección de paquete o revisar la interfaz en un ancho más estrecho. Esto convierte la matriz en una cola de reparación en lugar de un informe de progreso decorativo.

Ejecutar la app de Mac en cada localización admitida

Use la configuración de esquema de Xcode para comprobaciones repetibles a nivel de app. Elija Product > Scheme > Edit Scheme, seleccione Run, abra Options y elija App Language y App Region. Cierre el diálogo, seleccione el destino de ejecución de Mac y ejecute la app. Repita para las combinaciones admitidas en su auditoría. Apple documenta esta secuencia en Probar localizaciones al ejecutar su app.

Siga la misma ruta a través de la interfaz en cada ejecución. Ejercite cada mensaje con sus estados relevantes: una colección vacía, un solo elemento, varios elementos y etiquetas sintéticas más largas. Para mensajes plurales, elija valores adicionales necesarios para ejercitar las ramas presentes en esa localización; un conjunto fijo de conteo pequeño no establece cobertura completa de ramas.

Inspeccione oraciones completas, valores sustituidos, ajuste de línea, truncamiento y anchos de menú o control. Cuando un mensaje tiene dos conteos, varíelos independientemente. Por ejemplo, cambiar el conteo de elementos mientras se mantiene constante el conteo de grupos ayuda a revelar un error de mapeo de argumentos.

Las vistas previas de SwiftUI pueden acortar el ciclo de reparación. Apple admite establecer el valor de entorno locale de la vista previa y crear múltiples vistas previas localizadas después de agregar o importar esas localizaciones. Úselas para revisar una vista problemática, luego verifique la ruta real de la app. Consulte Vista previa de localizaciones.

Cierre la auditoría cuando cada par mensaje-localización requerido tenga una disposición documentada y se hayan verificado sus ramas necesarias. Preserve el inventario, la ruta de prueba y los hallazgos no resueltos juntos. Ese registro hace que la próxima auditoría sea accionable: un mensaje cambiado tiene una ubicación conocida, argumentos esperados, variantes requeridas y una forma repetible de inspeccionar su visualización.

Fuentes