Como localizar seu aplicativo iOS: Guia de internacionalização do SwiftUI

Prepare seu aplicativo Xcode, traduza .xcstrings com IA e, em seguida, faça o upload de capturas de tela para que a PTC (Private Translation Cloud) revise o aplicativo iOS renderizado em todos os idiomas. Este guia detalha o fluxo de trabalho completo usando SwiftUI e os String Catalogs do Xcode 15+, o caminho moderno recomendado pela Apple. Para a visão geral do serviço multiplataforma que abrange tanto iOS quanto Android, consulte traduzir aplicativos iOS e Android com IA.

Parte 1: Como funciona a localização no iOS

A localização no iOS é o processo de adaptar o texto, a formatação e os assets do seu aplicativo para suportar vários idiomas e regiões. Com os String Catalogs introduzidos no Xcode 15, o fluxo de trabalho é drasticamente mais simples do que a abordagem legada com .strings / .stringsdict.

Internacionalização vs. localização

Estas são duas etapas separadas e precisam acontecer nessa ordem:

• Internacionalização (i18n) é a base técnica. Você estrutura seu código para que texto, imagens e formatação possam variar por locale sem alterações no código. Feito uma vez, idealmente antes do seu primeiro lançamento.
• Localização (l10n) é o trabalho contínuo que se segue. Escrever traduções, ajustar layouts e fornecer assets específicos de locale para cada novo idioma.

O erro mais comum é tratar a localização como uma tarefa pós-lançamento, apenas para descobrir que a base de código não está pronta. Voltar para corrigir strings hardcoded, layouts de direção fixa e formatadores que não reconhecem o locale em um aplicativo existente leva muito mais tempo do que construir com a localização em mente desde o início.

Como o Xcode 15+ usa Localizable.xcstrings como uma única fonte de verdade

O modelo de localização da Apple no Xcode 15+ concentra-se em um único arquivo por target: Localizable.xcstrings. Este arquivo é um String Catalog formatado em JSON que contém seu idioma de origem mais todas as traduções, incluindo variações de plural, variações específicas de dispositivo e substituições.

O Xcode extrai automaticamente strings localizáveis do seu código SwiftUI (qualquer Text("..."), Label("...", systemImage:), Button("...") e qualquer interpolação de string que use LocalizedStringKey). Executar a build do seu aplicativo preenche o Localizable.xcstrings com cada string de origem extraída.

A Apple suporta vários formatos. .strings (chave-valor legado), .stringsdict (plurais legados) e .xcstrings (moderno). Novos projetos devem começar com .xcstrings. Projetos baseados em .strings existentes podem migrar via File > New > File > String Catalog e a opção de importação do Xcode. A documentação oficial de localização da Apple cobre todo o contexto.

Parte 2: Configure seu projeto Xcode para localização

Passo 1: Habilite a localização. Abra seu projeto no Xcode e selecione o arquivo do projeto no Navigator. Na aba Info, role até Localizations. O inglês já está listado como o idioma base. Clique em + para adicionar cada idioma de destino (espanhol, francês, árabe, etc.).

Passo 2: Crie um String Catalog. Clique com o botão direito no seu projeto e selecione New File from Template. Procure por String Catalog e adicione-o. Mantenha o nome padrão Localizable.xcstrings. Faça o build do projeto uma vez com Cmd+B. O Xcode escaneia seu código, encontra cada string localizável e preenche o catálogo automaticamente.

Passo 3: Marque as strings para localização. No SwiftUI, qualquer string literal passada para Text(_:), Label, rótulos de ação de Button, títulos de navegação, etc., é automaticamente LocalizedStringKey:

import SwiftUI

struct WelcomeView: View {
    let userName: String
    let unreadCount: Int

    var body: some View {
        VStack {
            Text("Welcome, \(userName)!")
            Text("You have \(unreadCount) unread messages")
            Button("Get Started") {
                // action
            }
        }
    }
}

Existem dois padrões onde o Xcode não consegue extrair strings automaticamente. Ambos falham silenciosamente:

Dica 1: Evite passar variáveis para Text. Quando você passa uma variável para uma view Text em vez de uma string literal, o SwiftUI a trata como uma string comum e pula totalmente a busca no catálogo:

// NOT localized - SwiftUI treats the variable as a plain String
let title = "welcome_title"
Text(title)

// Localized correctly
Text(LocalizedStringKey(title))

Dica 2: Use String(localized:) fora de views. Para strings que você precisa localizar em um view model, função auxiliar ou em qualquer lugar fora de uma view SwiftUI, use String(localized:) em vez de uma string comum:

let errorMessage = String(localized: "error_generic")

Passo 4: Adicione variantes de plural e dispositivo. As strings frequentemente precisam de formas diferentes dependendo do contexto.

Para pluralização, comece com a string na sua view SwiftUI:

Text("\(bookCount) books on your shelf")

Abra o String Catalog, clique com o botão direito na chave e escolha Vary by Plural. O Xcode gera as categorias de plural automaticamente e as preenche com a string de origem. Para o inglês, você verá One e Other. Corrija o campo One para "%lld book on your shelf". Marque ambas como revisadas.

Quando você enviar o catálogo posteriormente para a PTC, a estrutura de plural viaja com o arquivo. Para o árabe, a PTC gera traduções para todas as seis categorias de plural (zero, one, two, few, many, other) porque a gramática árabe exige todas as seis. O espanhol precisa de duas, assim como o inglês.

Para variações de dispositivo (por exemplo, “Toque para continuar” no iPhone vs. “Clique para continuar” no Mac), clique com o botão direito na chave e escolha Vary by Device. Adicione os dispositivos que você deseja personalizar e insira a string apropriada para cada um. O iOS serve a versão que corresponder ao dispositivo atual em tempo de execução.

Parte 3: Traduza seus .xcstrings com a PTC

Para projetos pequenos, você poderia abrir cada coluna de idioma no catálogo e digitar as traduções diretamente. À medida que seu aplicativo cresce, isso se torna incontrolável em centenas de chaves e dezenas de idiomas. A PTC lida com o upload, a tradução e a sincronização.

Passo 1: Exporte seu String Catalog a partir do Xcode. Vá para Product > Export Localizations. O Xcode empacota seu String Catalog em um arquivo .xcloc por idioma de destino. Para a PTC, você precisa apenas do arquivo .xcstrings dentro do pacote .xcloc. Clique com o botão direito no .xcloc exportado no Finder e selecione Show Package Contents para encontrar o Localizable.xcstrings.

Se você vir uma notificação “Unable to build project for localization string extraction”, seu projeto usa APIs exclusivas do iOS que o Xcode não consegue compilar contra seu SDK interno do macOS durante a extração de strings. Correção: selecione o target do projeto em TARGETS, vá para Build Settings, procure por “Use Compiler to Extract Swift Strings” e defina como No. Em seguida, exporte novamente.

Passo 2: Inscreva-se na PTC. O teste de 30 dias cobre 20.000 palavras em 2 idiomas, o que é suficiente para localizar a maioria dos aplicativos. Após o teste de 30 dias, a PTC funciona com Pay-As-You-Go. Sem assinatura, as primeiras 500 palavras de cada mês são gratuitas.

Passo 3: Configure seu projeto e traduza. Arraste o Localizable.xcstrings para a PTC. Deixe o nome do arquivo de saída como Localizable.xcstrings. O Xcode espera esse nome exato ao resolver strings localizadas. Selecione seus idiomas de destino.

A PTC gera automaticamente uma descrição do seu aplicativo a partir do arquivo enviado. Revise-a e edite se necessário. Se você tiver arquivos de tradução existentes, faça o upload deles para que a PTC possa corresponder ao seu estilo. Caso contrário, traduza do zero. Adicione termos ao glossário. A PTC adiciona o nome do seu aplicativo automaticamente. Adicione qualquer terminologia específica da marca que deva ser traduzida de uma maneira específica ou mantida sem tradução. Clique em Start Translation.

Passo 4: Revise e faça o download. Assim que a tradução estiver concluída, a aba Translations mostra cada string de origem ao lado de sua tradução. Qualquer pessoa que você adicionar ao projeto pode editar as traduções diretamente. Se algo não parecer certo, use a opção Relatar um problema para uma tradução específica e solicite uma retradução por IA gratuita. A PTC aprende com o feedback e o aplica a futuras strings no mesmo projeto.

Se alguma string traduzida exceder seu limite de comprimento, ela será destacada. Você tem três opções. Aceitar a tradução mais longa se sua interface puder acomodá-la. Solicitar uma retradução que se ajuste ao limite atual. Ajustar o limite em Configurações > Comprimentos de tradução.

Parte 4: Integre os .xcstrings traduzidos ao seu projeto Xcode

Você tem três opções.

Opção 1: Faça o download manual dos arquivos da PTC. Vá para a aba Resource Files e baixe o ZIP. Ele contém um único Localizable.xcstrings com suas strings de origem em inglês e todas as traduções. Feche o Xcode, substitua o Localizable.xcstrings existente na pasta do seu projeto pelo da PTC e reinicie o Xcode. Suas traduções aparecem no String Catalog com uma marca de seleção ao lado de cada idioma totalmente traduzido.

Opção 2: Integre com Git. Se o seu projeto estiver no GitHub, GitLab ou Bitbucket, conecte a PTC diretamente. A integração com Git é um recurso Pro. Ative o Pay-As-You-Go para acessá-lo. No seu painel da PTC, vá para Configurações > Merge Requests e clique em Add Git Integration. Forneça o URL do seu repositório, conceda acesso à PTC e escolha seu branch e arquivos de origem. A PTC envia um merge request com as traduções.

Opção 3: Use a API. A API da PTC oferece controle total sobre quando e como as traduções são extraídas para o seu pipeline de build. Com o Pay-As-You-Go ativado, vá para Configurações > Gerenciar tokens de API, clique em Add access token e consulte a referência da API da PTC para os endpoints.

Um seletor de idiomas no aplicativo (alguns aplicativos precisam disso) pode substituir o locale do sistema por view através do ambiente SwiftUI:

import SwiftUI

@MainActor
class LocaleManager: ObservableObject {
    @Published var currentLocale: Locale = .current

    func setLocale(_ identifier: String) {
        currentLocale = Locale(identifier: identifier)
        UserDefaults.standard.set([identifier], forKey: "AppleLanguages")
    }
}

struct LanguageSettingsView: View {
    @EnvironmentObject var localeManager: LocaleManager

    var body: some View {
        List {
            Button("English") { localeManager.setLocale("en") }
            Button("Español") { localeManager.setLocale("es") }
            Button("Français") { localeManager.setLocale("fr") }
        }
        .environment(\.locale, localeManager.currentLocale)
    }
}

Alterar o AppleLanguages em tempo de execução requer a reinicialização do aplicativo para algumas strings do sistema. A substituição do ambiente SwiftUI entra em vigor imediatamente para views dentro desse escopo.

Parte 5: Teste seu aplicativo iOS localizado

Teste com a configuração de idioma do scheme. A maneira mais rápida de testar um idioma específico é através do seu scheme no Xcode. Vá para Product > Scheme > Edit Scheme, clique na aba Options, mude App Language e App Region para o locale desejado e execute com Cmd+R. Funciona bem para a maioria dos idiomas. Você deve ver o mesmo layout e design do inglês, com todo o texto trocado.

Teste árabe e outros idiomas RTL. A configuração de idioma do scheme pode não ser confiável no Simulator para RTL. Use as próprias configurações de idioma do Simulator:

1. Execute o aplicativo com Cmd+R para abrir o Simulator.
2. Pressione Cmd+Home para ir à tela inicial.
3. Abra Settings > General > Language & Region.
4. Toque em Add Language, selecione o árabe e defina-o como o idioma principal.
5. O Simulator é reiniciado. Abra seu aplicativo a partir da tela inicial.

Verifique se o texto aparece em árabe e se o layout é espelhado corretamente, com o título de navegação e o conteúdo alinhados à direita. Para testes de visualização sem se comprometer com um idioma, Edit Scheme > Options > Application Language > Right-to-Left Pseudolanguage é uma verificação mais rápida. Para testes de expansão de texto, use Double-Length Pseudolanguage para ver como os layouts lidam com strings 30-40% mais longas antes de se comprometer com um idioma de destino.

Melhores práticas de localização no iOS

• Verifique sua interface para comprimentos de texto variados. O alemão é ~30% mais longo que o inglês. Francês e espanhol ~20%. Use o sistema de layout flexível do SwiftUI, deixe os rótulos crescerem e quebrarem de linha naturalmente, evite restrições de largura fixa em elementos de texto e teste em alguns idiomas diferentes durante o desenvolvimento.
• Não pule variantes de pluralização. O russo tem três categorias de plural, o árabe tem seis, o japonês não tem nenhuma. Os String Catalogs lidam com isso quando você adiciona o idioma. Certifique-se de que todos os campos gerados estejam preenchidos antes do lançamento.
• Localize imagens e assets. Imagens com texto ou visuais culturalmente específicos precisam de variantes localizadas. Em Assets.xcassets, selecione a imagem e, no Attributes Inspector, clique em Localize. Escolha os idiomas para os quais deseja variantes e substitua cada uma pela versão apropriada. O iOS exibe a imagem correta com base no locale do usuário.
• Mantenha seu idioma base completo. Seu idioma base (geralmente o inglês) é o fallback para qualquer tradução ausente. Uma base incompleta pode causar fallbacks inesperados, mesmo em idiomas que, de outra forma, estariam totalmente traduzidos. O Xcode sinaliza strings base ausentes ou desatualizadas durante a build.
• Localize sua ficha da loja de aplicativos. Um aplicativo localizado com uma ficha apenas em inglês perde usuários na descoberta. No App Store Connect, você pode localizar o nome do aplicativo, subtítulo, descrição e palavras-chave por território. As palavras-chave são particularmente valiosas. A Apple indexa palavras-chave de vários locales por território, multiplicando efetivamente seu orçamento de caracteres de palavras-chave além dos 100 caracteres padrão. Use o recurso Paste to Translate da PTC para o conteúdo da App Store.
• Use formatadores sensíveis ao locale. Formatadores sensíveis a Date.FormatStyle, Decimal.FormatStyle e Locale. Nunca deixe "$" ou "MM/DD/YYYY" hardcoded.
• Use %lld para contagens de números inteiros e String(localized: "You have ^[\(count) message](inflect: true)") onde a concordância gramatical automática da Apple se aplica.

Revisão visual de tradução do seu aplicativo iOS traduzido - publique sem QA manual por idioma

Depois que a PTC traduzir seus .xcstrings, você ainda precisa verificar o aplicativo em execução em todos os idiomas. Tradicionalmente, um passe de QA manual de vários dias por lançamento. Um rótulo traduzido pode estourar uma barra de navegação em alemão. “Send” pode ser traduzido como um substantivo em francês quando o botão precisava de um verbo. Uma string hardcoded em inglês fora de Text(_:) ficará visivelmente sem tradução no aplicativo iOS em execução.

O AI Visual QA da PTC substitui esse passe. Para aplicativos iOS nativos (o fluxo da extensão do navegador não se aplica), use o upload de captura de tela. Capture as telas críticas do aplicativo em execução em cada idioma de destino (login, aba principal, configurações, casos extremos) e faça o upload delas para a PTC. A IA de visão da PTC inspeciona cada tela e:

• Corrige problemas no .xcstrings quando a PTC os controla. Retraduz uma classe gramatical incorreta, escolhe um sinônimo mais curto que se ajuste a uma barra de navegação, regenera uma forma plural com a concordância gramatical correta.
• Gera um prompt do Cursor / Claude Code quando o problema reside no seu código Swift. Um LocalizedStringKey ausente, um String hardcoded fora do sistema de localização, uma frase construída por concatenação em vez de substituição.

A entrega: um aplicativo iOS verificado por lançamento. Não um .xcstrings traduzido com o QA manual ainda pela frente.

Traduza sua ficha da loja de aplicativos, notas de lançamento e notificações push

A descrição da sua App Store, as notas de lançamento de novidades e o texto das notificações push ficam fora do Localizable.xcstrings. O recurso Paste to Translate da PTC lida com esse texto no mesmo projeto. Cole o texto de origem no painel da PTC, escolha os idiomas de destino, receba de volta traduções que usam o mesmo glossário e voz da marca que as suas strings no aplicativo. A Apple indexa palavras-chave de vários locales por território, então fichas localizadas são particularmente valiosas para a descoberta.

Traduza o conteúdo do usuário no aplicativo com a API da PTC

Chats no aplicativo, postagens sociais e avaliações de usuários precisam de tradução à medida que o conteúdo chega. A API REST da PTC traduz esse conteúdo sob demanda com autenticação por token Bearer, usando o mesmo glossário e voz da marca que as suas traduções de .xcstrings.

Corrija a localização do iOS que não está funcionando

A causa mais comum é que o arquivo de localização não está incluído no target do aplicativo. Clique em Localizable.xcstrings no Navigator, abra o File Inspector e verifique se o target do seu aplicativo está marcado em Target Membership. Confirme também se o idioma está listado na seção Localizations do seu projeto, na aba Info. Se ambos parecerem corretos, limpe a pasta de build com Shift+Cmd+K e faça o build novamente.

Formatos de arquivo de localização do iOS: .xcstrings, .strings, .stringsdict, .xliff

O .xcstrings (String Catalog) é o padrão atual desde o Xcode 15. Um único arquivo baseado em JSON que consolida todas as strings, regras de plural e variantes específicas de dispositivos. O .strings é o formato de chave-valor legado, ainda válido em bases de código mais antigas, pareado com .stringsdict para plurais. .xliff e .xcloc são formatos de exportação para repassar aos tradutores. Eles não são formatos de armazenamento.

Localize o nome do seu aplicativo com InfoPlist.strings

Crie um arquivo InfoPlist.strings e localize-o para cada idioma suportado. Em cada versão de idioma, adicione CFBundleDisplayName = "Your Translated App Name";. Selecione o arquivo no Navigator, abra o File Inspector e clique em Localize para adicionar variantes de idioma. O iOS exibe o nome correto do aplicativo com base no idioma do dispositivo.

Altere o idioma do aplicativo iOS sem reiniciar

O iOS não fornece uma API nativa para isso. A abordagem padrão é definir o AppleLanguages em UserDefaults e pedir ao usuário para reiniciar:

UserDefaults.standard.set(["es"], forKey: "AppleLanguages")
UserDefaults.standard.synchronize()

A alteração entra em vigor na próxima vez que o aplicativo for iniciado. Se você precisar de alternância na mesma sessão sem reiniciar, terá que gerenciar a localização manualmente carregando o bundle apropriado para o idioma selecionado.

Por que o iOS faz fallback para o inglês em idiomas não suportados

O iOS usa seu idioma base como fallback quando uma tradução não está disponível. Este é o comportamento esperado. Para minimizar os fallbacks, certifique-se de que seu String Catalog não mostre strings ausentes ou desatualizadas antes de cada lançamento.

Quão precisa é a localização por IA para um aplicativo iOS inteiro

A PTC usa IA para traduzir arquivos .xcstrings, .strings e .stringsdict em minutos, preservando regras de plural e placeholders automaticamente. A maioria das strings traduzidas vai para produção sem edições. Para melhores resultados, informe a PTC sobre seu aplicativo durante a configuração, para que as traduções reflitam o tom e a terminologia corretos.

Em quais idiomas do iOS localizar primeiro

Espanhol, francês, alemão, japonês e chinês simplificado são pontos de partida comuns além do inglês. Se o seu aplicativo já tem usuários em uma região específica, priorize o idioma deles primeiro. Para o menor custo de adaptação, comece com idiomas geográfica ou culturalmente próximos ao seu mercado base.

Localize seu próprio aplicativo iOS

Comece com o teste de 30 dias da PTC - 20.000 palavras por nossa conta, sem cartão de crédito. Faça o upload do seu Localizable.xcstrings, traduza-o em minutos, depois faça o upload de capturas de tela e deixe a PTC verificar o aplicativo renderizado.

Relacionado:

• Traduza aplicativos iOS e Android com IA - visão geral do serviço multiplataforma.
• Como localizar seu aplicativo Android - o guia equivalente para o Android Studio.
• Referência da API da PTC - endpoints REST para integração de CI.