Communitygithub.com

Localización e Internacionalización

Guía completa para la localización de apps usando Catálogos de Cadenas, generación de símbolos type-safe (Xcode 26+), manejo de plurales, diseños RTL, formato según configuración regional y migración desde archivos .strings.

¿Qué es Localización e Internacionalización?

Esta habilidad proporciona una guía completa y actualizada para la localización de aplicaciones Apple, con un enfoque principal en los Catálogos de Cadenas (String Catalogs) introducidos en Xcode 15. Cubre todo el flujo de trabajo, desde la creación y estructura de archivos `.xcstrings` hasta la gestión de estados de traducción (nuevo, necesita revisión, revisado, obsoleto). Es útil para cualquier desarrollador que trabaje con SwiftUI, UIKit o App Intents y necesite soporte multilingüe, incluyendo características avanzadas como la localización diferida con `LocalizedStringResource`, el manejo correcto de plurales (con variaciones para idiomas con múltiples reglas como ruso o árabe), el diseño especular para idiomas de derecha a izquierda (RTL) y el formateo de fechas, números y monedas según la configuración regional del usuario. La habilidad también detalla estrategias de migración desde formatos legado (`.strings`, `.stringsdict`) y cubre las últimas novedades de Xcode 26, como la generación automática de símbolos y el macro `#bundle`. Su objetivo es centralizar las mejores prácticas de internacionalización para el ecosistema Apple, permitiendo a los desarrolladores crear aplicaciones que cumplan con los estándares de accesibilidad e inclusión, como los reconocidos por los premios Apple Design Award.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/IGTA-Tech/claude-skills-research/tree/HEAD/Axiom/.claude-plugin/plugins/axiom/skills/localization

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace Localización e Internacionalización?

Guía completa para la localización de aplicaciones usando Catálogos de Cadenas. Los ganadores del premio Apple Design Award a la Inclusividad siempre admiten múltiples idiomas con un excelente soporte para RTL (derecha a izquierda).

Descripción General

Los Catálogos de Cadenas (.xcstrings) son el formato unificado de Xcode 15 para gestionar la localización de aplicaciones. Reemplazan los archivos .strings y .stringsdict heredados con un único formato basado en JSON que es más fácil de mantener, comparar e integrar con flujos de trabajo de traducción.

Esta habilidad cubre Catálogos de Cadenas, APIs de localización de SwiftUI/UIKit, manejo de plurales, soporte RTL, formato según la configuración regional y estrategias de migración desde formatos heredados.

Cuándo Usar Esta Habilidad

  • Configurar Catálogos de Cadenas en Xcode 15+
  • Localizar aplicaciones SwiftUI y UIKit
  • Manejar formas plurales correctamente (crítico para muchos idiomas)
  • Admitir idiomas RTL (árabe, hebreo)
  • Formatear fechas, números y monedas según la configuración regional
  • Migrar desde archivos .strings/.stringsdict heredados
  • Preparar Accesos Directos de la App (App Shortcuts) e Intenciones de la App (App Intents) para localización
  • Depurar traducciones faltantes o formas plurales incorrectas

Requisitos del Sistema

  • Xcode 15+ para Catálogos de Cadenas (.xcstrings)
  • Xcode 26+ para generación automática de símbolos, macro #bundle y generación de comentarios con IA
  • iOS 15+ para LocalizedStringResource
  • iOS 16+ para localización de Accesos Directos de la App
  • Versiones anteriores de iOS usan archivos .strings heredados

Parte 1: Catálogos de Cadenas (WWDC 2023/10155)

Crear un Catálogo de Cadenas

Método 1: Navegador de Xcode

  1. Archivo → Nuevo → Archivo
  2. Elige "Catálogo de Cadenas"
  3. Nómbralo (ej., Localizable.xcstrings)
  4. Añádelo al destino

Método 2: Extracción Automática

Xcode 15 puede extraer automáticamente cadenas de:

  • Vistas SwiftUI (literales de cadena en Text, Label, Button)
  • Código Swift (String(localized:))
  • Objective-C (NSLocalizedString)
  • C (CFCopyLocalizedString)
  • Archivos de Interface Builder (.storyboard, .xib)
  • Valores de Info.plist
  • Frases de Accesos Directos de la App

Configuración de Build Requerida:

  • "Usar el compilador para extraer cadenas Swift" → Sí
  • "La localización prefiere Catálogos de Cadenas" → Sí

Estructura del Catálogo de Cadenas

Cada entrada tiene:

  • Clave: Identificador único (por defecto: la cadena en inglés)
  • Valor Predeterminado: Texto de respaldo si falta la traducción
  • Comentario: Contexto para los traductores
  • Tabla de Cadenas: Contenedor de organización (por defecto: "Localizable")

Ejemplo JSON de .xcstrings:

{
  "sourceLanguage" : "en",
  "strings" : {
    "¡Gracias por comprar con nosotros!" : {
      "comment" : "Etiqueta sobre el botón de pago",
      "localizations" : {
        "en" : {
          "stringUnit" : {
            "state" : "translated",
            "value" : "Thanks for shopping with us!"
          }
        },
        "es" : {
          "stringUnit" : {
            "state" : "translated",
            "value" : "¡Gracias por comprar con nosotros!"
          }
        }
      }
    }
  },
  "version" : "1.0"
}

Estados de Traducción

Xcode rastrea el estado de cada traducción:

  • Nuevo (⚪) - La cadena aún no se ha traducido
  • Necesita Revisión (🟡) - El origen cambió, la traducción puede estar desactualizada
  • Revisado (✅) - Traducción aprobada y actualizada
  • Obsoleto (🔴) - La cadena ya no se encuentra en el código fuente

Flujo de trabajo:

  1. El desarrollador añade una cadena → Nuevo
  2. El traductor añade la traducción → Revisado
  3. El desarrollador cambia el origen → Necesita Revisión
  4. El traductor actualiza → Revisado
  5. El desarrollador elimina el código → Obsoleto

Parte 2: Localización en SwiftUI

LocalizedStringKey (Automático)

Las vistas de SwiftUI con parámetros String admiten automáticamente la localización:

// ✅ Automáticamente localizable
Text("¡Bienvenido a la WWDC!")
Label("¡Gracias por comprar con nosotros!", systemImage: "bag")
Button("Pagar") { }

// Xcode extrae estas cadenas al Catálogo de Cadenas

Cómo funciona: SwiftUI usa LocalizedStringKey internamente, que busca cadenas en los Catálogos de Cadenas.

String(localized:) con Comentarios

Para localización explícita en código Swift:

// Básico
let titulo = String(localized: "¡Bienvenido a la WWDC!")

// Con comentario para traductores
let titulo = String(localized: "¡Bienvenido a la WWDC!",
                   comment: "Título del banner de notificación")

// Con tabla personalizada
let titulo = String(localized: "¡Bienvenido a la WWDC!",
                   table: "NotificacionesWWDC",
                   comment: "Título del banner de notificación")

// Con valor predeterminado (clave ≠ texto en inglés)
let titulo = String(localized: "TITULO_NOTIFICACION_WWDC",
                   defaultValue: "¡Bienvenido a la WWDC!",
                   comment: "Título del banner de notificación")

Mejor práctica: Incluye siempre comment para dar contexto a los traductores.

LocalizedStringResource (Localización Diferida)

Para pasar cadenas localizables a otras funciones:

import Foundation

struct VistaTarjeta: View {
    let titulo: LocalizedStringResource
    let subtitulo: LocalizedStringResource

    var body: some View {
        ZStack {
            RoundedRectangle(cornerRadius: 10.0)
            VStack {
                Text(titulo)      // Se resuelve en tiempo de renderizado
                Text(subtitulo)
            }
            .padding()
        }
    }
}

// Uso
VistaTarjeta(
    titulo: "Compras Recientes",
    subtitulo: "Artículos que has pedido en la última semana."
)

Diferencia clave: LocalizedStringResource retrasa la búsqueda hasta que se usa, permitiendo que las vistas personalizadas sean totalmente localizables.

AttributedString con Markdown

// El formato Markdown se conserva entre localizaciones
let subtitulo = AttributedString(localized: "**Negrita** y texto _cursiva_")

Parte 3: UIKit y Foundation

Macro NSLocalizedString

// Básico
let titulo = NSLocalizedString("Compras Recientes", comment: "Título del Botón")

// Con tabla
let titulo = NSLocalizedString("Compras Recientes",
                             tableName: "Compras",
                             comment: "Título del Botón")

// Con bundle
let titulo = NSLocalizedString("Compras Recientes",
                             tableName: nil,
                             bundle: .main,
                             value: "",
                             comment: "Título del Botón")

Bundle.localizedString

let bundlePersonalizado = Bundle(for: MiFramework.self)
let texto = bundlePersonalizado.localizedString(forKey: "Bienvenido",
                                        value: nil,
                                        table: "MiFramework")

Macros Personalizadas

// Objective-C
#define MiCadenaLocalizada(key, comment) \
    [miBundle localizedStringForKey:key value:nil table:nil]

Localización de Info.plist

Localiza el nombre de la app, permisos, etc.:

  1. Selecciona Info.plist
  2. Editor → Añadir Localización
  3. Crea InfoPlist.strings para cada idioma:
// InfoPlist.strings (Español)
"CFBundleName" = "Mi Aplicación";
"NSCameraUsageDescription" = "La app necesita acceso a la cámara para tomar fotos.";

Parte 4: Pluralización

Diferentes idiomas tienen diferentes reglas de plural:

  • Inglés: 2 formas (uno, otro)
  • Ruso: 3 formas (uno, pocos, muchos)
  • Polaco: 3 formas (uno, pocos, otro)
  • Árabe: 6 formas (cero, uno, dos, pocos, muchos, otro)

Manejo de Plurales en SwiftUI

// Xcode crea automáticamente variaciones plurales
Text("\(cuenta) artículos")

// Con formato personalizado
Text("\(cuentaVisitantes) Visitantes Recientes")

En el Catálogo de Cadenas:

{
  "strings" : {
    "%lld Visitantes Recientes" : {
      "localizations" : {
        "en" : {
          "variations" : {
            "plural" : {
              "one" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "%lld Recent Visitor"
                }
              },
              "other" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "%lld Recent Visitors"
                }
              }
            }
          }
        }
      }
    }
  }
}

Formato de Exportación XLIFF

Al exportar para traducción (Archivo → Exportar Localizaciones):

Legado (stringsdict):

<trans-unit id="/%lld Visitantes Recientes:dict/NSStringLocalizedFormatKey:dict/:string">
    <source>%#@visitantesRecientes@</source>
</trans-unit>

<trans-unit id="/%lld Visitantes Recientes:dict/visitantesRecientes:dict/one:dict/:string">
    <source>%lld Recent Visitor</source>
    <target>%lld Visitante Reciente</target>
</trans-unit>

Catálogo de Cadenas (más limpio):

<trans-unit id="%lld Visitantes Recientes|==|plural.one">
    <source>%lld Recent Visitor</source>
    <target>%lld Visitante Reciente</target>
</trans-unit>

<trans-unit id="%lld Visitantes Recientes|==|plural.other">
    <source>%lld Recent Visitors</source>
    <target>%lld Visitantes Recientes</target>
</trans-unit>

Sustituciones con Variables Plurales

// Múltiples variables con diferentes formas plurales
let mensaje = String(localized: "\(cuentaCanciones) canciones en \(cuentaAlbumes) álbumes")

Xcode crea variaciones para la forma plural de cada variable:

  • cuentaCanciones: uno, otro
  • cuentaAlbumes: uno, otro
  • Combinaciones totales: 2 × 2 = 4 entradas de traducción

Parte 5: Variaciones de Dispositivo y Ancho

Cadenas Específicas de Dispositivo

Texto diferente para diferentes plataformas:

// Mismo código, diferentes cadenas por dispositivo
Text("Tienda de Comida para Aves")

Variaciones en el Catálogo de Cadenas:

{
  "Tienda de Comida para Aves" : {
    "localizations" : {
      "en" : {
        "variations" : {
          "device" : {
            "applewatch" : {
              "stringUnit" : {
                "value" : "Bird Food"
              }
            },
            "other" : {
              "stringUnit" : {
                "value" : "Bird Food Shop"
              }
            }
          }
        }
      }
    }
  }
}

Resultado:

  • iPhone/iPad: "Bird Food Shop"
  • Apple Watch: "Bird Food" (más corto para pantalla pequeña)

Variaciones de Ancho

Para tipos dinámicos y clases de tamaño:

Text("Configuración de la Aplicación")

El Catálogo de Cadenas puede proporcionar texto más corto para anchos estrechos.


Parte 6: Soporte RTL

Reflejo del Diseño

SwiftUI refleja automáticamente los diseños para idiomas RTL:

// ✅ Se refleja automáticamente para árabe/hebreo
HStack {
    Image(systemName: "chevron.right")
    Text("Siguiente")
}

// iPhone (Inglés): [>] Siguiente
// iPhone (Árabe):  Siguiente [<]

Leading/Trailing vs Izquierda/Derecha

Usa siempre direcciones semánticas:

// ✅ Correcto - se refleja automáticamente
.padding(.leading, 16)
.frame(maxWidth: .infinity, alignment: .leading)

// ❌ Incorrecto - no se refleja
.padding(.left, 16)
.frame(maxWidth: .infinity, alignment: .left)

Imágenes e Iconos

Marca las imágenes que deben o no deben voltearse:

// ✅ Direccional - se refleja para RTL
Image(systemName: "chevron.forward")

// ✅ No direccional - nunca se refleja
Image(systemName: "star.fill")

// Imágenes personalizadas
Image("botonAtras")
    .flipsForRightToLeftLayoutDirection(true)

Pruebas en Modo RTL

Esquema de Xcode:

  1. Editar Esquema → Ejecutar → Opciones
  2. Idioma de la Aplicación: Árabe / Hebreo
  3. O: Idioma de la App → Pseudolenguaje de Derecha a Izquierda

Simulador: Configuración → General → Idioma y Región → Orden de Idiomas Preferidos

Vista Previa en SwiftUI:

struct VistaContenido_Previews: PreviewProvider {
    static var previews: some View {
        VistaContenido()
            .environment(\.layoutDirection, .rightToLeft)
            .environment(\.locale, Locale(identifier: "ar"))
    }
}

Parte 7: Formato Según Configuración Regional

DateFormatter

let formateador = DateFormatter()
formateador.locale = Locale.current  // ✅ Usa la configuración regional actual
formateador.dateStyle = .long
formateador.timeStyle = .short

let cadenaFecha = formateador.string(from: Date())

// EE. UU.: "January 15, 2024 at 3:30 PM"
// Francia: "15 janvier 2024 à 15:30"
// Japón: "2024年1月15日 15:30"

Nunca codifiques cadenas de formato de fecha:

// ❌ Incorrecto - se rompe en otras configuraciones regionales
formateador.dateFormat = "MM/dd/yyyy"

// ✅ Correcto - se adapta a la configuración regional
formateador.dateStyle = .short

NumberFormatter para Moneda

let formateador = NumberFormatter()
formateador.locale = Locale.current
formateador.numberStyle = .currency

let cadenaPrecio = formateador.string(from: 29.99)

// EE. UU.: "$29.99"
// Reino Unido: "£29.99"
// Japón: "¥30" (redondea a entero)
// Francia: "29,99 €" (coma decimal, espacio antes del símbolo)

MeasurementFormatter

let distancia = Measurement(value: 100, unit: UnitLength.meters)

let formateador = MeasurementFormatter()
formateador.locale = Locale.current

let cadenaDistancia = formateador.string(from: distancia)

// EE. UU.: "328 ft" (convierte a imperial)
// Países métricos: "100 m"

Ordenación Específica de la Configuración Regional

let nombres = ["Ångström", "Zebra", "Apple"]

// ✅ Ordenación consciente de la configuración regional
let ordenados = nombres.sorted { (lhs, rhs) in
    lhs.localizedStandardCompare(rhs) == .orderedAscending
}

// Suecia: ["Ångström", "Apple", "Zebra"]  (Å va primero en sueco)
// EE. UU.: ["Ångström", "Apple", "Zebra"]      (Å se trata como A)

Parte 8: Localización de Accesos Directos de la App

Frases con Parámetros

import AppIntents

struct IntencionMostrarDonasPrincipales: AppIntent {
    static var title: LocalizedStringResource = "Mostrar Donas Principales"

    @Parameter(title: "Período de Tiempo")
    var periodo: Periodo

    static var parameterSummary: some ParameterSummary {
        Summary("\(.applicationName) Tendencias para \(\$\.periodo)") {
            \$\.periodo
        }
    }
}

Catálogo de Cadenas capturará:

  • "Mostrar Donas Principales" (título de la intención)
  • "Período de Tiempo" (título del parámetro)
  • "\(.applicationName) Tendencias para \(\$\.periodo)" (resumen del parámetro)

Variaciones de Plural en Accesos Directos

struct IntencionMostrarEstado: AppIntent {
    static var title: LocalizedStringResource = "Mostrar Estado de la Cuenta"

    @Parameter(title: "ID de la Cuenta")
    var idCuenta: String

    static var parameterSummary: some ParameterSummary {
        Summary("Mostrar estado de la cuenta \(\$\.idCuenta)")
    }

    // Xcode maneja automáticamente variaciones plurales de "cuenta"
    // cuando se usa en Siri
}

Parte 9: Símbolos Type-Safe (Xcode 26+)

Generación Automática de Símbolos

Xcode 26+ puede generar automáticamente símbolos type-safe a partir de Catálogos de Cadenas:

// Sintaxis tradicional (pre-Xcode 26)
let bienvenida = String(localized: "Bienvenido a la App")

// Sintaxis con macro `#bundle` (Xcode 26+)
let bienvenida = #bundle("Bienvenido a la App")

// Alternativa: acceso de símbolo generado automáticamente
let bienvenida = String(localized: LocalizableStrings.welcomeToTheApp)

Beneficios de los Símbolos Type-Safe

  • Seguridad en tiempo de compilación: Los errores tipográficos en las claves de localización se capturan en tiempo de compilación
  • Autocompletado: Xcode proporciona autocompletado para todas las cadenas localizables
  • Refactorización: Renombrar una clave de localización actualiza automáticamente todas las referencias

Requisitos

  • Xcode 26+
  • Catálogos de Cadenas habilitados para el destino
  • "Generar Símbolos de Localización" → Sí (configuración de Build)

Ejemplo

// Catálogo de Cadenas contiene:
// "Pantalla de Bienvenida" = "Bienvenido a Nuestra App"

// Xcode 26+ genera automáticamente:
// enum LocalizableStrings {
//     static let welcomeScreen: LocalizedStringResource = ...
// }

// Uso:
Text(LocalizableStrings.welcomeScreen)

Parte 10: Migración desde Formatos Heredados

Migración Automática

Xcode 15+ proporciona migración automática:

  1. Abre tu proyecto
  2. Selecciona tu archivo .strings o .stringsdict
  3. Editor → Migrar a Catálogo de Cadenas

Xcode:

  • Conserva todas las traducciones existentes
  • Convierte reglas de plural a variaciones de plural en el Catálogo de Cadenas
  • Marca las cadenas migradas como "Revisado"

Migración Manual

Para proyectos complejos, usa el script de Python de Apple:

# Instalar script (una vez)
pip3 install -U apple-localization-tool

# Migrar proyecto
python3 -m apple_localization_tool \
    --input /ruta/a/tu/proyecto \
    --output /ruta/al/nuevo/catalogo

Comprobación Después de la Migración

  1. Verifica que todos los archivos heredados se hayan eliminado de la compilación
  2. Verifica el estado de las traducciones: Las cadenas migradas deben aparecer como "Revisado"
  3. Prueba la app: Ejecuta la app en varios idiomas para asegurarte de que las cadenas se muestren correctamente

Mejores Prácticas

Manejo de Cadenas

  1. Usa nombres de claves descriptivos: "MENSAJE_BIENVENIDA" es mejor que "str1"
    • Pero: Usa el inglés como clave a menos que tengas una razón para no hacerlo
  2. Proporciona contexto: Siempre añade un comment a String(localized:)
  3. Mantén las cadenas cortas: Las cadenas largas son difíciles de traducir y admitir en pantallas pequeñas
  4. Sé consistente: Usa la misma clave para el mismo texto en toda la app

RTL y Diseño

  1. Usa direcciones semánticas (leading, trailing) en lugar de absolutas (left, right)
  2. Prueba temprano: Verifica el diseño RTL al inicio del desarrollo
  3. Marca correctamente las imágenes: Usa flipsForRightToLeftLayoutDirection para imágenes direccionales

Pruebas y Garantía de Calidad

  1. Pseudolocalización: Usa las funciones de pseudolenguaje de Xcode (Archivo → Editar → Configuración de Esquema)
  2. Prueba de cadenas largas: Las traducciones al alemán son a menudo un 30% más largas que el inglés
  3. Prueba de plurales: Verifica los plurales para todos los idiomas compatibles
  4. Prueba de formato: Verifica fechas, números y monedas para cada configuración regional

Recursos

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

IGTA-Tech/claude-skills-research

Use when implementing SwiftUI animations, understanding VectorArithmetic, using @Animatable macro, choosing between spring and timing curve animations, or debugging animation behavior - comprehensive animation reference from iOS 13 through iOS 26

IGTA-Tech/claude-skills-research

Use when CAAnimation completion handler doesn't fire, spring physics look wrong on device, animation duration mismatches actual time, gesture + animation interaction causes jank, or timing differs between simulator and real hardware - systematic CAAnimation diagnosis with CATransaction patterns, frame rate awareness, and device-specific behavior

IGTA-Tech/claude-skills-research

This skill should be used when comparing two videos to analyze compression results or quality differences. Generates interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Triggers when users mention "compare videos", "video quality", "compression analysis", "before/after compression", or request quality assessment of compressed videos.

IGTA-Tech/claude-skills-research

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

IGTA-Tech/claude-skills-research

Write high-converting landing page copy using proven frameworks like PAS (Problem-Agitate-Solution), AIDA, and StoryBrand. Creates headlines, value propositions, CTAs, and full page sections optimized for conversion. Use when users need landing page copy, sales page content, or marketing website text.

IGTA-Tech/claude-skills-research

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

IGTA-Tech/claude-skills-research

Download YouTube video transcripts when user provides a YouTube URL or asks to download/get/fetch a transcript from YouTube. Also use when user wants to transcribe or get captions/subtitles from a YouTube video.

Skills relacionados