Para validar los marcadores de posición de una traducción en tu Mac, compara la posición, el tipo y el uso previsto de cada argumento con el mensaje de origen. Usa los diagnósticos de incompatibilidad de Xcode; luego revisa las sustituciones plurales y prueba la etiqueta renderizada con valores de muestra distintos.

Esta guía está dirigida a quien revisa etiquetas localizadas de una app para Mac en Xcode. La tarea consiste en comparar un mensaje y sus traducciones con los valores que proporciona la app. Todas las etiquetas que aparecen a continuación son ejemplos sintéticos en inglés; ilustran mecanismos de formato y no son traducciones reales.

¿Qué debe incluir el contrato de argumentos de un mensaje?

Un contrato de argumentos es un registro de revisión que describe los valores que recibe un mensaje: sus posiciones, tipos de formato, significados y usos previstos. Es una lista de comprobación práctica derivada del código fuente y del catálogo, no un formato de archivo independiente de Apple.

String.LocalizationValue de Swift admite cadenas localizables con valores de tiempo de ejecución interpolados. Su documentación también distingue entre usar el texto de origen como clave de localización y proporcionar una clave independiente con un valor predeterminado. Por consiguiente, puede que un identificador por sí solo no revele los argumentos del mensaje: inspecciona el texto de origen predeterminado y el punto donde se invoca. String.LocalizationValue

Considera la cadena de formato Added %lld items to %@. Para este ejemplo, la app proporciona primero un recuento entero y después una etiqueta de colección respaldada por un objeto. Anota el contrato antes de editar la traducción:

Posición del argumento Significado Formato esperado Valor ilustrativo
1 Número de elementos añadidos %lld 7
2 Etiqueta de la colección de destino %@ Canvas

La referencia de formatos de Apple define %@ como una conversión de objeto, %d como un entero con signo de 32 bits, %f como una conversión de tipo double y ll como el modificador de longitud entero para long long. También documenta formatos posicionales como %1$@. Conserva toda la información de tipo: cambiar %lld por %d cambia el tipo de entero esperado. La referencia está archivada, así que consúltala para la sintaxis de formato junto con la documentación actual de catálogos. Especificadores de formato de cadenas

Añade los significados de los argumentos al registro de revisión incluso cuando sus tipos sean idénticos. En Moved %@ to %@, una comprobación de tipos no puede distinguir la etiqueta del elemento de la etiqueta de destino. Una sintaxis correcta también requiere que los valores mantengan la relación adecuada con las palabras.

¿Cómo encuentras la fuente de referencia en Xcode?

Empieza con el proyecto abierto en Xcode e identifica el catálogo que contiene el mensaje. Si la fuente ha cambiado, elige Product > Build para actualizar las cadenas extraídas. Selecciona el catálogo en el navegador del proyecto, elige Editor > Assistant y selecciona la clave del mensaje para ver su fuente. Apple documenta este flujo de trabajo para localizar y actualizar entradas del catálogo. Localizar y variar texto con un catálogo de cadenas

Comprueba qué valores proporciona realmente el punto de invocación, en qué orden y a través de qué API de localización. Apple recomienda usar API localizables como String(localized:); un inicializador con un defaultValue independiente usa su primer parámetro como clave y el segundo como cadena de origen predeterminada. Esto importa cuando un identificador neutro como collection.added.summary representa el mensaje. Preparar el texto de la app para su traducción

Registra juntos tres elementos: el catálogo y la clave, el texto de origen predeterminado y los significados y tipos ordenados de los argumentos. Si no coinciden, resuelve la discrepancia antes de ajustar las traducciones. De lo contrario, podrías adaptar una traducción a una fuente desactualizada en lugar de a las entradas actuales de la app.

Añade también contexto para futuras ediciones. Apple permite incluir comentarios en las cadenas localizables para explicar su uso. Un comentario sintético útil indicaría que el argumento 1 es el recuento de elementos y el argumento 2 es la etiqueta de la colección de destino. Así se proporciona al localizador información que un especificador de formato no puede expresar. Preparar el texto de la app para su traducción

¿Cómo compruebas la cantidad, los tipos y las posiciones de los argumentos?

Apple incorporó la validación de catálogos de cadenas para detectar problemas comunes, como incompatibilidades entre especificadores de formato, y ofrece soluciones para algunos de ellos. Revisa cualquier diagnóstico que Xcode muestre para la entrada. Considera las correcciones sugeridas como propuestas para reparar la sintaxis y verifica que conserven el significado del mensaje. Crear apps preparadas para varios idiomas

Para un mensaje sencillo sin sustituciones plurales, sigue esta secuencia de revisión:

  1. Identifica cada marcador de posición que consume un argumento en el texto de origen y en el texto candidato.
  2. Asigna cada marcador de posición a la posición de su argumento.
  3. Compara el tipo de formato completo con el contrato.
  4. Comprueba que cada valor requerido aparezca donde lo espera el texto.
  5. Investiga por separado las referencias añadidas, omitidas o repetidas.

La notación posicional permite cambiar el orden de las palabras en una traducción y conservar la identidad de los argumentos. En %2$@: added %1$lld items, el primer marcador visible hace referencia al argumento 2 y el segundo al argumento 1. Apple documenta la sintaxis posicional n$. Especificadores de formato de cadenas

La siguiente tabla de decisión se aplica al contrato ilustrativo de dos argumentos anterior. Son resultados de revisión propuestos, no resultados de ejecutar Xcode:

Texto de formato candidato Resultado de la revisión Motivo
Added %lld items to %@ Coincide con el contrato sencillo Primero el recuento, después el destino
%2$@: added %1$lld items Coincide tras reordenar Las posiciones explícitas conservan la identidad de ambos argumentos
Added %d items to %@ Corrige el tipo de entero El argumento 1 ya no usa el modificador de longitud esperado
Added %lld items Investiga la omisión Falta el destino requerido por este mensaje
Added %1$lld items to %1$@ Corrige las referencias Se hace referencia al argumento 1 con tipos incompatibles; falta el argumento 2
Added %1$lld items to %2$@ (%2$@) Revisa la repetición Hay tres apariciones, pero solo se hace referencia a dos argumentos distintos

Mantén separado el recuento de apariciones del recuento de argumentos distintos. La última fila muestra intencionalmente la diferencia: repetir el argumento 2 no crea un tercer valor proporcionado. Decidir si esa repetición corresponde al texto es una decisión editorial. Para esta tarea, márcala hasta que se aclare su propósito.

Del mismo modo, no cuentes cada signo de porcentaje como un argumento. Apple define %% como un signo de porcentaje literal. Una etiqueta de formato como Scale: %lld%% contiene un marcador de valor y un signo de porcentaje escapado. Especificadores de formato de cadenas

¿Por qué las sustituciones plurales requieren otra comprobación?

Los mensajes plurales requieren revisar tanto el mecanismo de selección como el texto que muestra un valor. En su sesión sobre catálogos de cadenas, Apple explica que las sustituciones pueden contener diccionarios de casos plurales. El inspector muestra la posición del argumento que controla la selección y su especificador de formato de estilo C. Por tanto, una sustitución puede depender de un argumento aunque una rama concreta no lo imprima como número. Descubrir los catálogos de cadenas

Para un mensaje sintético sobre el recuento de elementos, compara One item added con %lld items added. La primera rama escribe la cantidad con palabras; la segunda la muestra como número. Una regla que exigiera la misma cantidad de marcadores visibles en todas las ramas rechazaría innecesariamente la primera. El comportamiento documentado por Apple para los diccionarios de cadenas permite explícitamente omitir el especificador numérico de formato en las formas plurales y da como opción escribir el número con palabras. Formato de archivo Stringsdict

Usa esta revisión por ramas:

  • Verifica en el inspector la posición y el tipo del argumento que controla la sustitución.
  • Inspecciona todas las ramas plurales presentes para la localización de destino.
  • Comprueba cada marcador de posición mostrado con el argumento al que hace referencia.
  • Explica cualquier omisión numérica en la forma de mostrar el texto de la rama.
  • Comprueba por separado los demás argumentos del mensaje; escribir un recuento con palabras no explica la ausencia de una etiqueta de colección.

Si hay dos recuentos que varían de forma independiente, conserva sus funciones separadas. Un mensaje sintético sobre elementos y colecciones necesita que el recuento de elementos controle la sustitución de elementos y que el recuento de colecciones controle la sustitución de colecciones. Apple documenta varias sustituciones dentro de un mismo mensaje y explica que el resultado en tiempo de ejecución combina sus casos plurales seleccionados. Descubrir los catálogos de cadenas

¿Cómo confirmas el mensaje corregido en tu Mac?

Después de corregir la entrada, compila la app e inspecciona los diagnósticos de catálogo que sigan apareciendo. Luego ejecuta la pantalla pertinente en la localización de destino. El flujo de trabajo admitido por Apple consiste en elegir Product > Scheme > Edit Scheme, seleccionar Run, abrir Options, elegir App Language y el App Region correspondiente, hacer clic en Close y ejecutar el destino seleccionado. Probar localizaciones al ejecutar la app

Elige valores de muestra que permitan detectar intercambios. Para dos argumentos de recuento, usa números distintos, como 2 y 7. Para dos argumentos de texto, usa etiquetas distintas, como Tile y Canvas. Son datos de prueba ilustrativos: su propósito es revelar qué valor proporcionado aparece en cada parte del mensaje.

En los mensajes con formas plurales, prueba valores que lleguen a las ramas que estás revisando. Cuando dos sustituciones varíen de forma independiente, incluye combinaciones que cambien un recuento mientras el otro permanece fijo. Inspecciona tanto el texto seleccionado como la ubicación de cada valor mostrado. Si una combinación se renderiza correctamente, las demás ramas siguen sin comprobarse.

Mantén separado el estado de traducción de la comprobación del contrato. Apple describe la marca de verificación verde del catálogo como el estado traducido una vez que se ha introducido el texto. Registra las comprobaciones que realmente realizaste —asignación de argumentos, comparación de tipos, inspección de ramas y ejemplos renderizados— en lugar de tratar ese indicador como prueba de las cuatro. Localizar y variar texto con un catálogo de cadenas

El mensaje está listo para continuar cuando sus marcadores de posición se resuelven con los argumentos proporcionados previstos, sus tipos coinciden y cualquier omisión o repetición específica de una rama tiene una explicación clara. Mantener ese contrato breve junto al mensaje facilita evaluar la siguiente edición de la fuente o la traducción.

Fuentes