Localização & Internacionalização
Guia completo para localização de aplicativos usando Catálogos de Strings. Os vencedores do Apple Design Award de Inclusividade sempre suportam vários idiomas com excelente suporte a RTL (da Direita para a 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 legados arquivos .strings e .stringsdict por um formato único baseado em JSON que é mais fácil de manter, fazer diff e integrar com fluxos de trabalho de tradução.
Esta skill cobre Catálogos de Strings, APIs de localização do SwiftUI/UIKit, manipulação de plurais, suporte RTL, formatação sensível a localidade e estratégias de migração de formatos legados.
Quando Usar Esta Skill
- Configurando Catálogos de Strings no Xcode 15+
- Localizando aplicativos SwiftUI e UIKit
- Lidando corretamente com formas plurais (crítico para muitos idiomas)
- Suportando idiomas RTL (Árabe, Hebraico)
- Formatando datas, números e moedas por localidade
- Migrando de arquivos
.strings/.stringsdictlegados - Preparando App Shortcuts e App Intents para localização
- Depurando 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 "Catálogo de Strings"
- Nomeie-o (ex.:
Localizable.xcstrings) - Adicione ao alvo
Método 2: Extração Automática
O Xcode 15 pode extrair strings automaticamente 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:
- "Usar Compilador para Extrair Strings Swift" → Sim
- "Localização Prefere Catálogos de Strings" → Sim
Estrutura do Catálogo de Strings
Cada entrada tem:
- Chave: Identificador único (padrão: a string em inglês)
- Valor Padrão: Fallback se a tradução estiver faltando
- Comentário: Contexto para tradutores
- Tabela de Strings: Contêiner de organização (padrão: "Localizable")
Exemplo de JSON .xcstrings:
{
"sourceLanguage" : "en",
"strings" : {
"Obrigado por comprar conosco!" : {
"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:
- Novo (⚪) - A string ainda não foi traduzida
- Precisa de Revisão (🟡) - A fonte mudou, a tradução pode estar desatualizada
- Revisado (✅) - Tradução aprovada e atual
- Obsoleto (🔴) - A string não é mais encontrada no código fonte
Fluxo de Trabalho:
- Desenvolvedor adiciona string → Novo
- Tradutor adiciona tradução → Revisado
- Desenvolvedor altera a fonte → Precisa de Revisão
- Tradutor atualiza → Revisado
- Desenvolvedor remove código → Obsoleto
Parte 2: Localização SwiftUI
LocalizedStringKey (Automática)
Views SwiftUI com parâmetros String suportam automaticamente localização:
// ✅ Automaticamente localizável
Text("Bem-vindo à WWDC!")
Label("Obrigado por comprar conosco!", systemImage: "bag")
Button("Finalizar Compra") { }
// Xcode extrai essas strings para o Catálogo de Strings
Como funciona: 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: "NotificacoesWWDC",
comment: "Título do banner de notificação")
// Com valor padrão (chave ≠ texto em inglês)
let titulo = String(localized: "TITULO_NOTIFICACAO_WWDC",
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 CartaoView: 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
CartaoView(
titulo: "Compras Recentes",
subtitulo: "Itens que você pediu na última semana."
)
Diferença chave: LocalizedStringResource adia a busca até ser usado, 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 bundlePersonalizado = Bundle(for: MeuFramework.self)
let texto = bundlePersonalizado.localizedString(forKey: "Bem-vindo",
value: nil,
table: "MeuFramework")
Macros Personalizadas
// Objective-C
#define MinhaStringLocalizada(chave, comentario) \
[meuBundle localizedStringForKey:chave 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 (Português)
"CFBundleName" = "Meu Aplicativo";
"NSCameraUsageDescription" = "O app precisa de acesso à câmera para tirar 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)
Manipulação de Plurais no SwiftUI
// Xcode cria automaticamente variações plurais
Text("\(contagem) itens")
// Com formatação personalizada
Text("\(contagemVisitantes) Visitantes Recentes")
No Catálogo de Strings:
{
"strings" : {
"%lld Visitantes Recentes" : {
"localizations" : {
"en" : {
"variations" : {
"plural" : {
"one" : {
"stringUnit" : {
"state" : "translated",
"value" : "%lld Recent Visitor"
}
},
"other" : {
"stringUnit" : {
"state" : "translated",
"value" : "%lld Recent Visitors"
}
}
}
}
}
}
}
}
}
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(\