Localização e Internacionalização
Guia completo para localização de aplicativos usando Catálogos de Strings. Os vencedores do Apple Design Award Inclusivity sempre oferecem suporte a múltiplos idiomas com excelente suporte a RTL (Direita para Esquerda).
Visão Geral
Os Catálogos de Strings (.xcstrings) são o formato unificado do Xcode 15 para gerenciar a localização de aplicativos. Eles substituem os arquivos legados .strings e .stringsdict por um formato único baseado em JSON, mais fácil de manter, fazer diff e integrar com fluxos de tradução.
Este skill aborda Catálogos de Strings, APIs de localização para SwiftUI/UIKit, tratamento de plurais, suporte RTL, formatação sensível a locale e estratégias de migração de formatos legados.
Quando Usar Este Skill
- Configurar Catálogos de Strings no Xcode 15+
- Localizar aplicativos SwiftUI e UIKit
- Lidar corretamente com formas plurais (crítico para muitos idiomas)
- Suportar idiomas RTL (árabe, hebraico)
- Formatar datas, números e moedas conforme o locale
- Migrar de arquivos
.strings/.stringsdictlegados - Preparar App Shortcuts e App Intents para localização
- Depurar traduções ausentes ou formas plurais incorretas
Requisitos do Sistema
- Xcode 15+ para Catálogos de Strings (
.xcstrings) - Xcode 26+ para geração automática de símbolos, macro
#bundlee geração de comentários com IA - iOS 15+ para
LocalizedStringResource - iOS 16+ para localização de App Shortcuts
- Versões anteriores do iOS usam arquivos
.stringslegados
Parte 1: Catálogos de Strings (WWDC 2023/10155)
Criando um Catálogo de Strings
Método 1: Navegador do Xcode
- Arquivo → Novo → Arquivo
- Escolha "String Catalog"
- Nomeie (ex.:
Localizable.xcstrings) - Adicione ao alvo
Método 2: Extração Automática
O Xcode 15 pode extrair automaticamente strings de:
- Views SwiftUI (literais de string em
Text,Label,Button) - Código Swift (
String(localized:)) - Objective-C (
NSLocalizedString) - C (
CFCopyLocalizedString) - Arquivos Interface Builder (
.storyboard,.xib) - Valores do Info.plist
- Frases de App Shortcuts
Configurações de Build Necessárias:
- "Use Compiler to Extract Swift Strings" → Sim
- "Localization Prefers String Catalogs" → Sim
Estrutura do Catálogo de Strings
Cada entrada possui:
- Chave: Identificador único (padrão: a string em inglês)
- Valor Padrão: Fallback se a tradução estiver faltando
- Comentário: Contexto para os tradutores
- Tabela de Strings: Contêiner de organização (padrão: "Localizable")
Exemplo de JSON .xcstrings:
{
"sourceLanguage" : "en",
"strings" : {
"Thanks for shopping with us!" : {
"comment" : "Rótulo acima do botão de finalizar compra",
"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 Tradução
O Xcode rastreia o estado de cada tradução:
- Nova (⚪) - A string ainda não foi traduzida
- Revisão Necessária (🟡) - A fonte mudou, a tradução pode estar desatualizada
- Revisada (✅) - Tradução aprovada e atual
- Obsoleta (🔴) - A string não é mais encontrada no código fonte
Fluxo de Trabalho:
- Desenvolvedor adiciona string → Nova
- Tradutor adiciona tradução → Revisada
- Desenvolvedor altera fonte → Revisão Necessária
- Tradutor atualiza → Revisada
- Desenvolvedor remove código → Obsoleta
Parte 2: Localização em SwiftUI
LocalizedStringKey (Automática)
Views SwiftUI com parâmetros String suportam localização automaticamente:
// ✅ Automaticamente localizável
Text("Bem-vindo à WWDC!")
Label("Obrigado por comprar conosco!", systemImage: "bag")
Button("Finalizar Compra") { }
// O Xcode extrai essas strings para o Catálogo de Strings
Como funciona: O SwiftUI usa LocalizedStringKey internamente, que busca strings nos Catálogos de Strings.
String(localized:) com Comentários
Para localização explícita em código Swift:
// Básico
let titulo = String(localized: "Bem-vindo à WWDC!")
// Com comentário para tradutores
let titulo = String(localized: "Bem-vindo à WWDC!",
comment: "Título do banner de notificação")
// Com tabela personalizada
let titulo = String(localized: "Bem-vindo à WWDC!",
table: "WWDCNotificacoes",
comment: "Título do banner de notificação")
// Com valor padrão (chave ≠ texto em inglês)
let titulo = String(localized: "WWDC_NOTIFICATION_TITLE",
defaultValue: "Bem-vindo à WWDC!",
comment: "Título do banner de notificação")
Melhor prática: Sempre inclua comment para dar contexto aos tradutores.
LocalizedStringResource (Localização Adiada)
Para passar strings localizáveis para outras funções:
import Foundation
struct CardView: View {
let titulo: LocalizedStringResource
let subtitulo: LocalizedStringResource
var body: some View {
ZStack {
RoundedRectangle(cornerRadius: 10.0)
VStack {
Text(titulo) // Resolvido no momento da renderização
Text(subtitulo)
}
.padding()
}
}
}
// Uso
CardView(
titulo: "Compras Recentes",
subtitulo: "Itens que você pediu na semana passada."
)
Diferença chave: LocalizedStringResource adia a busca até o uso, permitindo que views personalizadas sejam totalmente localizáveis.
AttributedString com Markdown
// A formatação Markdown é preservada entre localizações
let subtitulo = AttributedString(localized: "Texto **negrito** e _itálico_")
Parte 3: UIKit e Foundation
Macro NSLocalizedString
// Básico
let titulo = NSLocalizedString("Compras Recentes", comment: "Título do Botão")
// Com tabela
let titulo = NSLocalizedString("Compras Recentes",
tableName: "Compras",
comment: "Título do Botão")
// Com bundle
let titulo = NSLocalizedString("Compras Recentes",
tableName: nil,
bundle: .main,
value: "",
comment: "Título do Botão")
Bundle.localizedString
let customBundle = Bundle(for: MyFramework.self)
let texto = customBundle.localizedString(forKey: "Bem-vindo",
value: nil,
table: "MeuFramework")
Macros Personalizadas
// Objective-C
#define MyLocalizedString(key, comment) \
[myBundle localizedStringForKey:key value:nil table:nil]
Localização do Info.plist
Localize nome do app, permissões, etc.:
- Selecione
Info.plist - Editor → Adicionar Localização
- Crie
InfoPlist.stringspara cada idioma:
// InfoPlist.strings (Espanhol)
"CFBundleName" = "Mi Aplicación";
"NSCameraUsageDescription" = "La app necesita acceso a la cámara para tomar fotos.";
Parte 4: Pluralização
Idiomas diferentes têm regras de plural diferentes:
- Inglês: 2 formas (one, other)
- Russo: 3 formas (one, few, many)
- Polonês: 3 formas (one, few, other)
- Árabe: 6 formas (zero, one, two, few, many, other)
Tratamento de Plural em SwiftUI
// O Xcode cria automaticamente variações de plural
Text("\(count) itens")
// Com formatação personalizada
Text("\(visitanteCount) Visitantes Recentes")
No Catálogo de Strings:
{
"strings" : {
"%lld Visitantes Recentes" : {
"localizations" : {
"en" : {
"variations" : {
"plural" : {
"one" : {
"stringUnit" : {
"state" : "translated",
"value" : "%lld Visitante Recente"
}
},
"other" : {
"stringUnit" : {
"state" : "translated",
"value" : "%lld Visitantes Recentes"
}
}
}
}
}
}
}
}
}
Formato de Exportação XLIFF
Ao exportar para tradução (Arquivo → Exportar Localizações):
Legado (stringsdict):
<trans-unit id="/%lld Visitantes Recentes:dict/NSStringLocalizedFormatKey:dict/:string">
<source>%#@visitantesRecentes@</source>
</trans-unit>
<trans-unit id="/%lld Visitantes Recentes:dict/visitantesRecentes:dict/one:dict/:string">
<source>%lld Visitante Recente</source>
<target>%lld Recent Visitor</target>
</trans-unit>
Catálogo de Strings (mais limpo):
<trans-unit id="%lld Visitantes Recentes|==|plural.one">
<source>%lld Visitante Recente</source>
<target>%lld Recent Visitor</target>
</trans-unit>
<trans-unit id="%lld Visitantes Recentes|==|plural.other">
<source>%lld Visitantes Recentes</source>
<target>%lld Recent Visitors</target>
</trans-unit>
Substituições com Variáveis Plurais
// Múltiplas variáveis com diferentes formas plurais
let mensagem = String(localized: "\(contagemMusicas) músicas em \(contagemAlbuns) álbuns")
O Xcode cria variações para a forma plural de cada variável:
contagemMusicas: one, othercontagemAlbuns: one, other- Combinações totais: 2 × 2 = 4 entradas de tradução
Parte 5: Variações de Dispositivo e Largura
Strings Específicas por Dispositivo
Texto diferente para plataformas diferentes:
// Mesmo código, strings diferentes por dispositivo
Text("Loja de Comida para Pássaros")
Variações no Catálogo de Strings:
{
"Loja de Comida para Pássaros" : {
"localizations" : {
"en" : {
"variations" : {
"device" : {
"applewatch" : {
"stringUnit" : {
"value" : "Comida para Pássaros"
}
},
"other" : {
"stringUnit" : {
"value" : "Loja de Comida para Pássaros"
}
}
}
}
}
}
}
}
Resultado:
- iPhone/iPad: "Loja de Comida para Pássaros"
- Apple Watch: "Comida para Pássaros" (mais curto para tela pequena)
Variações de Largura
Para tipo dinâmico e classes de tamanho:
Text("Configurações do Aplicativo")
O Catálogo de Strings pode fornecer texto mais curto para larguras estreitas.
Parte 6: Suporte RTL
Espelhamento de Layout
O SwiftUI espelha layouts automaticamente para idiomas RTL:
// ✅ Espelha automaticamente para árabe/hebraico
HStack {
Image(systemName: "chevron.right")
Text("Próximo")
}
// iPhone (Inglês): [>] Próximo
// iPhone (Árabe): Próximo [<]
Leading/Trailing vs Esquerda/Direita
Sempre use direções semânticas:
// ✅ Correto - espelha automaticamente
.padding(.leading, 16)
.frame(maxWidth: .infinity, alignment: .leading)
// ❌ Errado - não espelha
.padding(.left, 16)
.frame(maxWidth: .infinity, alignment: .left)
Imagens e Ícones
Marque imagens que devem ou não ser invertidas:
// ✅ Direcional - espelha para RTL
Image(systemName: "chevron.forward")
// ✅ Não direcional - nunca espelha
Image(systemName: "star.fill")
// Imagens personalizadas
Image("botaoVoltar")
.flipsForRightToLeftLayoutDirection(true)
Testando no Modo RTL
Scheme do Xcode:
- Editar Scheme → Executar → Opções
- Idioma do Aplicativo: Árabe / Hebraico
- OU: Idioma do App → Pseudoidioma da Direita para Esquerda
Simulador: Ajustes → Geral → Idioma e Região → Ordem de Idioma Preferencial
Preview do SwiftUI:
struct ContentView_Previews: PreviewProvider {
static var previews: some View {
ContentView()
.environment(\.layoutDirection, .rightToLeft)
.environment(\.locale, Locale(identifier: "ar"))
}
}
Parte 7: Formatação Sensível a Locale
DateFormatter
let formatador = DateFormatter()
formatador.locale = Locale.current // ✅ Use o locale atual
formatador.dateStyle = .long
formatador.timeStyle = .short
let dataString = formatador.string(from: Date())
// EUA: "15 de janeiro de 2024 às 3:30 PM"
// França: "15 janvier 2024 à 15:30"
// Japão: "2024年1月15日 15:30"
Nunca codifique strings de formato de data:
// ❌ Errado - quebra em outros locales
formatador.dateFormat = "MM/dd/yyyy"
// ✅ Correto - adapta ao locale
formatador.dateStyle = .short
NumberFormatter para Moeda
let formatador = NumberFormatter()
formatador.locale = Locale.current
formatador.numberStyle = .currency
let precoString = formatador.string(from: 29.99)
// EUA: "$29.99"
// Reino Unido: "£29.99"
// Japão: "¥30" (arredonda para inteiro)
// França: "29,99 €" (vírgula decimal, espaço antes do símbolo)
MeasurementFormatter
let distancia = Measurement(value: 100, unit: UnitLength.meters)
let formatador = MeasurementFormatter()
formatador.locale = Locale.current
let distanciaString = formatador.string(from: distancia)
// EUA: "328 pés" (converte para imperial)
// Países métricos: "100 m"
Ordenação Específica por Locale
let nomes = ["Ångström", "Zebra", "Maçã"]
// ✅ Ordenação sensível a locale
let ordenados = nomes.sorted { (lhs, rhs) in
lhs.localizedStandardCompare(rhs) == .orderedAscending
}
// Suécia: ["Ångström", "Maçã", "Zebra"] (Å vem primeiro em sueco)
// EUA: ["Maçã", "Zebra", "Ångström"] (Å tratado como A)
Parte 8: Localização de App Shortcuts
Frases com Parâmetros
import AppIntents
struct IntentMostrarDonutsTop: AppIntent {
static var titulo: LocalizedStringResource = "Mostrar Donuts Principais"
@Parameter(title: "Período")
var periodo: Periodo
static var sumarioParametros: some ParameterSummary {
Summary("\(.applicationName) Tendências para \(\.$periodo)") {
\(\.$periodo)
}
}
}
O Catálogo de Strings extrai automaticamente:
- Título do Intent
- Nomes dos parâmetros
- Modelos de frase com espaços reservados
Frases localizadas:
Inglês: "Food Truck Trends for this week"
Espanhol: "Tendencias de Food Truck para esta semana"
Localização do AppShortcutsProvider
struct AtalhosFoodTruck: AppShortcutsProvider {
static var atalhosApp: [AppShortcut] {
AppShortcut(
intent: IntentMostrarDonutsTop(),
phrases: [
"\(.applicationName) Tendências para \(\.$periodo)",
"Mostrar tendências de donuts",
"O que é popular em \(.applicationName)",
]
)
}
}
Parte 9: Migração de Formatos Legados
De .strings para Catálogo de Strings
Passo 1: Remova todos os arquivos .strings do projeto.
Passo 2: Crie um Catálogo de Strings vazio.
Passo 3: Habilite "Localization Prefers String Catalogs" nas configurações de build.
Passo 4: Execute o app — o Xcode automaticamente:
- Extrai strings do código-fonte
- Marca como Traduzido strings com arquivos
.stringsexistentes - Preserva o estado de todos os IDs de tradução
Migração Manual: Alguns desenvolvedores preferem uma migração em fases, usando um script de build para copiar traduções de .strings para .xcstrings via API de linha de comando do Xcode.
De .stringsdict para Catálogo de Strings
Migração com Script:
# Exemplo de script de migração usando plutil e ferramentas do Xcode
plutil -convert json Localizable.stringsdict -o temp.json
# Extrair chaves e valores plurais
# Mapear para formato de variações do `.xcstrings`
Migração Manual: Abra .stringsdict e .xcstrings lado a lado, copie chaves plurais e valores de substituições de formato.
Parte 10: Recursos Avançados (Xcode 26+)
Geração Automática de Símbolos
Xcode 26 gera constantes type-safe para chaves de Catálogo de Strings:
// ❌ Antes (propenso a erros)
let texto = String(localized: "Bem-vindo à WWDC!")
// ✅ Após (type-safe, com autocompletar)
let texto = String(localized: .Localizable.welcomeToWWDC)
Isso elimina erros de digitação e garante que strings removidas sejam detectadas em tempo de compilação.
Macro #bundle para Frameworks
A macro #bundle simplifica a obtenção de recursos localizados de um módulo Swift:
// Sem #bundle
let bundle = Bundle.module
let texto = String(localized: "Saudação", bundle: bundle)
// Com #bundle (Xcode 26+)
let texto = String(localized: "Saudação", bundle: #bundle)
Isso reduz a verbosidade e possíveis bugs ao referenciar bundles de módulo.
Geração de Comentários com IA
Xcode 26 pode gerar automaticamente comentários para entradas do Catálogo de Strings:
- Selecione uma entrada no editor do Catálogo de Strings
- Escolha Editor → Gerar Comentário com IA
- O Xcode analisa o código-fonte e gera um comentário descrevendo:
- Onde a string é usada
- Comprimento máximo esperado
- Contexto (se é botão, rótulo, etc.)
- Palavras-chave e variáveis
Dica: Revise os comentários gerados por IA antes de enviar para tradução.
Solução de Problemas
Strings não aparecendo no Catálogo
- Verifique se "Use Compiler to Extract Swift Strings" está Ativado
- Certifique-se de que literais de string não sejam concatenados em tempo de execução:
// ❌ Não extraído
let chave = "Bem-vindo" + " à WWDC!"
// ✅ Extraído
let chave = String(localized: "Bem-vindo à WWDC!")
- Verifique se há erros de compilação que impeçam a extração
- Execute Produto → Limpar Pasta de Build e reconstrua
Formas Plurais Incorretas
- Verifique a forma plural correta para o idioma alvo no CLDR Suplementar de Regras de Plural
- Para plurais complexos (russo, polonês, árabe), edite manualmente o JSON do Catálogo de Strings
- Teste com valores de contagem específicos (0, 1, 2, 3, 5, 21, 101) no Preview do SwiftUI
Traduções Não Aplicadas
- Verifique se o arquivo de localização está incluído no alvo da compilação
- Confirme se o idioma está listado nas Localizações do projeto
- Para módulos de framework, verifique se o recurso está no bundle correto
- Use o depurador de localização: Product → Perform Action → Show Localization Diagnostics
Aviso "LocalizedStringKey inferido com valor não interpolado"
Adicione interpolação explícita:
// ❌ Aviso
Text(minhaString)
// ✅ Correção
Text(\(minhaString))
Este aviso indica que a string não será pesquisada no catálogo. A correção com \(\)) força a pesquisa.