Localización e Internacionalización
Guía completa para la localización de aplicaciones usando Catálogos de Cadenas. Las aplicaciones ganadoras del premio Apple Design Award Inclusivity siempre soportan múltiples idiomas con excelente soporte 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 heredados .strings y .stringsdict con un único formato basado en JSON que es más fácil de mantener, versionar e integrar con flujos de trabajo de traducción.
Este skill 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 este skill
- Configurar Catálogos de Cadenas en Xcode 15+
- Localizar aplicaciones SwiftUI y UIKit
- Manejar correctamente las formas plurales (crítico para muchos idiomas)
- Dar soporte a idiomas RTL (árabe, hebreo)
- Formatear fechas, números y monedas según la configuración regional
- Migrar desde archivos
.strings/.stringsdictheredados - Preparar App Shortcuts y 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
#bundley generación de comentarios con IA - iOS 15+ para
LocalizedStringResource - iOS 16+ para localización de App Shortcuts
- Versiones anteriores de iOS usan archivos
.stringsheredados
Parte 1: Catálogos de Cadenas (WWDC 2023/10155)
Crear un Catálogo de Cadenas
Método 1: Navegador de Xcode
- Archivo → Nuevo → Archivo
- Elige "String Catalog"
- Asígnale un nombre (ej.,
Localizable.xcstrings) - Añádelo al target
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 App Shortcuts
Ajustes de compilación necesarios:
- "Use Compiler to Extract Swift Strings" → Sí
- "Localization Prefers String Catalogs" → Sí
Estructura del Catálogo de Cadenas
Cada entrada tiene:
- Clave (Key): Identificador único (por defecto, la cadena en inglés)
- Valor por defecto (Default Value): Valor de respaldo si falta la traducción
- Comentario (Comment): Contexto para los traductores
- Tabla de cadenas (String Table): Contenedor de organización (por defecto: "Localizable")
Ejemplo de JSON de .xcstrings:
{
"sourceLanguage" : "en",
"strings" : {
"Thanks for shopping with us!" : {
"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 (New) (⚪) - La cadena aún no se ha traducido
- Necesita revisión (Needs Review) (🟡) - El origen cambió, la traducción puede estar desactualizada
- Revisado (Reviewed) (✅) - Traducción aprobada y actual
- Obsoleto (Stale) (🔴) - La cadena ya no se encuentra en el código fuente
Flujo de trabajo:
- El desarrollador añade una cadena → Nuevo
- El traductor añade la traducción → Revisado
- El desarrollador cambia el origen → Necesita revisión
- El traductor actualiza → Revisado
- El desarrollador elimina el código → Obsoleto
Parte 2: Localización en SwiftUI
LocalizedStringKey (Automático)
Las vistas de SwiftUI con parámetros String soportan automáticamente la localización:
// ✅ Automáticamente localizable
Text("Welcome to WWDC!")
Label("Thanks for shopping with us!", systemImage: "bag")
Button("Checkout") { }
// Xcode extrae estas cadenas al Catálogo de Cadenas
Cómo funciona: SwiftUI usa internamente LocalizedStringKey, que busca las cadenas en los Catálogos de Cadenas.
String(localized:) con Comentarios
Para localización explícita en código Swift:
// Básico
let title = String(localized: "Welcome to WWDC!")
// Con comentario para traductores
let title = String(localized: "Welcome to WWDC!",
comment: "Título del banner de notificación")
// Con tabla personalizada
let title = String(localized: "Welcome to WWDC!",
table: "WWDCNotifications",
comment: "Título del banner de notificación")
// Con valor por defecto (clave ≠ texto en inglés)
let title = String(localized: "WWDC_NOTIFICATION_TITLE",
defaultValue: "Welcome to WWDC!",
comment: "Título del banner de notificación")
Mejor práctica: Incluye siempre un comment para dar contexto a los traductores.
LocalizedStringResource (Localización Diferida)
Para pasar cadenas localizables a otras funciones:
import Foundation
struct CardView: View {
let title: LocalizedStringResource
let subtitle: LocalizedStringResource
var body: some View {
ZStack {
RoundedRectangle(cornerRadius: 10.0)
VStack {
Text(title) // Se resuelve en tiempo de renderizado
Text(subtitle)
}
.padding()
}
}
}
// Uso
CardView(
title: "Recent Purchases",
subtitle: "Items you've ordered in the past week."
)
Diferencia clave: LocalizedStringResource retrasa la búsqueda hasta que se usa, permitiendo que las vistas personalizadas sean totalmente localizables.
AttributedString con Markdown
// El formateo Markdown se conserva entre localizaciones
let subtitle = AttributedString(localized: "**Bold** and _italic_ text")
Parte 3: UIKit y Foundation
Macro NSLocalizedString
// Básico
let title = NSLocalizedString("Recent Purchases", comment: "Título del botón")
// Con tabla
let title = NSLocalizedString("Recent Purchases",
tableName: "Shopping",
comment: "Título del botón")
// Con bundle
let title = NSLocalizedString("Recent Purchases",
tableName: nil,
bundle: .main,
value: "",
comment: "Título del botón")
Bundle.localizedString
let customBundle = Bundle(for: MyFramework.self)
let text = customBundle.localizedString(forKey: "Welcome",
value: nil,
table: "MyFramework")
Macros personalizadas
// Objective-C
#define MyLocalizedString(key, comment) \
[myBundle localizedStringForKey:key value:nil table:nil]
Localización de Info.plist
Localiza el nombre de la app, permisos, etc.:
- Selecciona
Info.plist - Editor → Añadir localización
- Crea
InfoPlist.stringspara 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 (one, other)
- Ruso: 3 formas (one, few, many)
- Polaco: 3 formas (one, few, other)
- Árabe: 6 formas (zero, one, two, few, many, other)
Manejo de plurales en SwiftUI
// Xcode crea automáticamente variaciones plurales
Text("\(count) items")
// Con formato personalizado
Text("\(visitorCount) Recent Visitors")
En el Catálogo de Cadenas:
{
"strings" : {
"%lld Recent Visitors" : {
"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 Recent Visitors:dict/NSStringLocalizedFormatKey:dict/:string">
<source>%#@recentVisitors@</source>
</trans-unit>
<trans-unit id="/%lld Recent Visitors:dict/recentVisitors: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 Recent Visitors|==|plural.one">
<source>%lld Recent Visitor</source>
<target>%lld Visitante Reciente</target>
</trans-unit>
<trans-unit id="%lld Recent Visitors|==|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 message = String(localized: "\(songCount) songs on \(albumCount) albums")
Xcode crea variaciones para la forma plural de cada variable:
songCount: one, otheralbumCount: one, other- Combinaciones totales: 2 × 2 = 4 entradas de traducción
Parte 5: Variaciones por Dispositivo y Ancho
Cadenas específicas para dispositivos
Texto diferente para diferentes plataformas:
// Mismo código, diferentes cadenas por dispositivo
Text("Bird Food Shop")
Variaciones en el Catálogo de Cadenas:
{
"Bird Food Shop" : {
"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 por ancho
Para tipo dinámico y clases de tamaño:
Text("Application Settings")
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("Next")
}
// iPhone (Inglés): [>] Next
// iPhone (Árabe): Next [<]
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/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("backButton")
.flipsForRightToLeftLayoutDirection(true)
Pruebas en modo RTL
Esquema de Xcode:
- Editar esquema → Ejecutar → Opciones
- Idioma de la aplicación: Árabe / Hebreo
- O: Idioma de la app → Seudo-idioma de derecha a izquierda
Simulador: Ajustes → General → Idioma y región → Orden de idioma preferido
Vista previa de SwiftUI:
struct ContentView_Previews: PreviewProvider {
static var previews: some View {
ContentView()
.environment(\.layoutDirection, .rightToLeft)
.environment(\.locale, Locale(identifier: "ar"))
}
}
Parte 7: Formato según la configuración regional
DateFormatter
let formatter = DateFormatter()
formatter.locale = Locale.current // ✅ Usa la configuración regional actual
formatter.dateStyle = .long
formatter.timeStyle = .short
let dateString = formatter.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
formatter.dateFormat = "MM/dd/yyyy"
// ✅ Correcto - se adapta a la configuración regional
formatter.dateStyle = .short
NumberFormatter para moneda
let formatter = NumberFormatter()
formatter.locale = Locale.current
formatter.numberStyle = .currency
let priceString = formatter.string(from: 29.99)
// EE.UU.: "$29.99"
// Reino Unido: "£29.99"
// Japón: "¥30" (redondea a entero)
// Francia: "29,99 €" (coma como decimal, espacio antes del símbolo)
MeasurementFormatter
let distance = Measurement(value: 100, unit: UnitLength.meters)
let formatter = MeasurementFormatter()
formatter.locale = Locale.current
let distanceString = formatter.string(from: distance)
// EE.UU.: "328 ft" (convierte a sistema imperial)
// Países métricos: "100 m"
Ordenación específica de la configuración regional
let names = ["Ångström", "Zebra", "Apple"]
// ✅ Ordenación sensible a la configuración regional
let sorted = names.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 App Shortcuts
Frases con parámetros
import AppIntents
struct ShowTopDonutsIntent: AppIntent {
static var title: LocalizedStringResource = "Show Top Donuts"
@Parameter(title: "Timeframe")
var timeframe: Timeframe
static var parameterSummary: some ParameterSummary {
Summary("\(.applicationName) Trends for \(\.$timeframe)") {
\.$timeframe
}
}
}
El Catálogo de Cadenas extrae automáticamente:
- El título del intent
- Los nombres de los parámetros
- Las plantillas de frases con marcadores de posición
Frases localizadas:
Inglés: "Food Truck Trends for this week"
Español: "Tendencias de Food Truck para esta semana"
Localización de AppShortcutsProvider
struct FoodTruckShortcuts: AppShortcutsProvider {
static var appShortcuts: [AppShortcut] {
AppShortcut(
intent: ShowTopDonutsIntent(),
phrases: [
"\(.applicationName) Trends for \(\.$timeframe)",
"Show trending donuts in \(\.$timeframe)",
"\(.applicationName) donut trends"
],
shortTitle: "Donut Trends",
systemImageName: "chart.line.uptrend.xyaxis"
)
}
}
Mejor práctica: Proporciona múltiples frases para que Siri pueda reconocer la intención de diferentes maneras. Cada frase se traduce por separado.
Parte 9: Estrategias de migración
Desde .strings a .xcstrings
- Añade un Catálogo de Cadenas a tu proyecto
- Importa archivos .strings existentes: Archivo → Importar… → Elegir archivos
.strings - Xcode fusiona las traducciones automáticamente
- Marca advertencias: Xcode mostrará errores/aviso si hay entradas duplicadas o conflictos
- Actualiza el código: Cambia
NSLocalizedStringporString(localized:)gradualmente
Desde .stringsdict a .xcstrings
Xcode maneja la migración de plurales automáticamente:
- Añade Catálogo de Cadenas
- Importa archivos
.stringsdict - Xcode convierte las reglas de plural al nuevo formato de variaciones
- Verifica: Revisa las variaciones en el editor visual de Xcode
Migración gradual
Puedes usar ambos formatos simultáneamente:
- El Catálogo de Cadenas tiene prioridad sobre
.strings - Mezcla y combina mientras migras archivo por archivo
- Usa
tablepara mantener tablas separadas
Parte 10: Depuración
Herramientas de localización de Xcode
Exportar localización:
- Archivo → Exportar Localizaciones… → XLIFF
- Arquivo → Importar Localizaciones… → XLIFF
Ejecutar con seudo-idioma: Esquema → Ejecutar → Opciones → Seudo-idioma
- Seudo-idioma de derecha a izquierda: Prueba diseño RTL sin traducción real
- Seudo-idioma de doble longitud: Prueba truncamiento de cadenas
Problemas comunes
Cadena no localizada:
- Verifica que la cadena esté en el Catálogo de Cadenas
- Asegúrate de que el estado de traducción sea "Revisado"
- Comprueba que la cadena use
LocalizedStringKeyoString(localized:)
Forma plural incorrecta:
- Verifica las variaciones en el Catálogo de Cadenas
- Prueba con diferentes valores (0, 1, 2, 5, 100)
- Recuerda que los idiomas tienen diferentes reglas plurales
Diseño RTL roto:
- Reemplaza
.leading/.trailingpor.left/.right - Marca imágenes direccionales con
flipsForRightToLeftLayoutDirection(true) - Prueba con seudo-idioma RTL
Error de formato de fecha:
- Reemplaza
dateFormatpordateStyle/timeStyle - Usa
DateFormattercon la configuración regional actual - Prueba con diferentes configuraciones regionales
Mejores prácticas
- Siempre proporciona comentarios para los traductores
- Usa SemanticUI (leading/trailing) en lugar de direcciones absolutas (left/right)
- Prueba con seudo-idiomas antes de traducir
- Automatiza las exportaciones de localización en CI/CD
- Mantén las cadenas cortas para dispositivos con pantallas pequeñas
- Evita cadenas concatenadas - usa formatos con marcadores de posición
- Prueba los plurales con todos los valores posibles (0, 1, 2, 3, etc.)
- Internacionaliza el código desde el comienzo del proyecto