Skip to main content

O guia completo para localizar aplicações iOS

De Localizable.strings aos metadados da App Store: localize a sua aplicação iOS com Xcode, SwiftUI, Fastlane e tradução automatizada com IA.

1

Ativar a localização no Xcode

Abra as definições do projeto Xcode, aceda a Info > Localizations e adicione os idiomas pretendidos. O Xcode cria automaticamente diretórios .lproj para cada idioma.

Xcode Project Settings
// In Xcode:
// 1. Select your project in the navigator
// 2. Go to Info tab > Localizations
// 3. Click + to add languages (e.g., German, Japanese)
// 4. Select which files to localize
//
// Xcode creates .lproj directories automatically:
// en.lproj/Localizable.strings
// de.lproj/Localizable.strings
// ja.lproj/Localizable.strings
A localização Base separa a interface das respetivas cadeias. Quando adiciona um idioma, o Xcode propõe criar versões localizadas dos seus storyboards, XIB e ficheiros de cadeias.
2

Criar Localizable.strings

O ficheiro normal de localização de iOS utiliza pares de chave e valor separados por sinais de igual, com um ponto e vírgula no fim de cada linha. Coloque-o na pasta Base.lproj do idioma de origem.

Base.lproj/Localizable.strings
// Base.lproj/Localizable.strings

"welcome_title" = "Welcome to MyApp";
"login_button" = "Sign In";
"settings_label" = "Settings";
"greeting" = "Hello, %@!";    // %@ = string placeholder
"item_count" = "%d items";     // %d = integer placeholder
A falta de pontos e vírgulas provoca falhas silenciosas: o ficheiro é carregado sem erros, mas as traduções ficam vazias. Certifique-se também de que o ficheiro foi adicionado à fase de compilação Copy Bundle Resources do destino; caso contrário, não será incluído no pacote da aplicação.
Common .strings Mistakes
// ❌ Common mistakes in .strings files:

// Missing semicolon — file loads but translations are empty
"welcome_title" = "Welcome"

// Unescaped quotes — causes parse error
"message" = "Click "here" to continue";

// ✅ Correct versions:
"welcome_title" = "Welcome";
"message" = "Click \"here\" to continue";
3

Migrar para catálogos de cadeias (Xcode 15 ou posterior)

Os catálogos de cadeias (.xcstrings) são a alternativa moderna da Apple aos ficheiros .strings. Oferecem um editor visual no Xcode, extração automática de cadeias das vistas SwiftUI e compatibilidade integrada com plurais.

Localizable.xcstrings
// Xcode 15+ String Catalog (Localizable.xcstrings)
// Xcode automatically extracts strings from your code
// and manages translations in a visual editor.

// In SwiftUI, strings are automatically localizable:
Text("Welcome to MyApp")
Text("Hello, \(userName)!")

// Mark strings explicitly:
let title = String(localized: "welcome_title")
Os catálogos de cadeias guardam TODOS os idiomas num único ficheiro JSON .xcstrings. Nas equipas, isto provoca conflitos frequentes de integração no Git quando várias pessoas adicionam cadeias. Em projetos grandes, considere um catálogo por módulo.
4

Utilizar cadeias localizadas em SwiftUI e UIKit

A vista Text do SwiftUI localiza automaticamente os literais de cadeia. UIKit utiliza NSLocalizedString. No iOS 16 ou posterior, a API moderna String(localized:comment:) oferece uma sintaxe mais simples e compatibilidade integrada no compilador.

ContentView.swift
import SwiftUI

struct ContentView: View {
    let userName: String

    var body: some View {
        VStack {
            // ✅ SwiftUI auto-localizes string literals
            Text("welcome_title")

            // ⚠️ This does NOT localize (String interpolation)
            // Text("Hello, \(userName)")

            // ✅ Use String(localized:) for dynamic strings
            Text(String(localized: "greeting \(userName)"))

            // ✅ UIKit style (works everywhere)
            let title = NSLocalizedString(
                "settings_label",
                comment: "Settings screen title"
            )

            // ✅ Modern API (iOS 16+)
            let modern = String(
                localized: "welcome_title",
                comment: "Main screen title"
            )
        }
    }
}
Text("Hello \(name)") falha silenciosamente na localização quando name é uma variável String simples. A interpolação de cadeias do SwiftUI cria uma LocalizedStringKey, mas apenas tipos específicos —Int, Double, etc.— são interpolados corretamente. Nas variáveis String, utilize primeiro String(localized:) para criar a cadeia localizada.
5

Tratar plurais

O iOS utiliza ficheiros .stringsdict para as regras de plural e é compatível com todas as categorias CLDR: zero, one, two, few, many e other. Os catálogos de cadeias tratam os plurais através de um editor visual no Xcode, muito mais simples do que escrever manualmente o XML de stringsdict.

Localizable.stringsdict
<!-- Localizable.stringsdict -->
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
    <key>items_count</key>
    <dict>
        <key>NSStringLocalizedFormatKey</key>
        <string>%#@count@</string>
        <key>count</key>
        <dict>
            <key>NSStringFormatSpecTypeKey</key>
            <string>NSStringPluralRuleType</string>
            <key>NSStringFormatValueTypeKey</key>
            <string>d</string>
            <key>zero</key>
            <string>No items</string>
            <key>one</key>
            <string>%d item</string>
            <key>other</key>
            <string>%d items</string>
        </dict>
    </dict>
</dict>
</plist>

// Usage in Swift:
String(format: NSLocalizedString("items_count", comment: ""),
       itemCount)
Idiomas como o árabe têm 6 formas plurais, o russo tem 3 e o japonês tem 1. Defina sempre todas as categorias CLDR necessárias nos idiomas de destino. Os catálogos de cadeias simplificam a tarefa através do editor visual de plurais.
6

Localizar metadados da App Store com Fastlane

Utilize a ferramenta deliver do Fastlane para manter os metadados da App Store —nome da aplicação, subtítulo, descrição, palavras-chave e notas da versão— sob controlo de versões no seu repositório, como ficheiros de texto simples organizados por região.

Terminal
# Install Fastlane
$ gem install fastlane

# Initialize deliver for App Store metadata
$ fastlane deliver init

# Directory structure created:
# fastlane/metadata/
# ├── en-US/
# │   ├── name.txt            # App name (30 chars)
# │   ├── subtitle.txt        # Subtitle (30 chars)
# │   ├── description.txt     # Full description
# │   ├── keywords.txt        # Search keywords (100 chars)
# │   ├── release_notes.txt   # What's New
# │   └── promotional_text.txt
# ├── de-DE/
# │   └── ...
# └── ja/
#     └── ...

# Push metadata to App Store Connect:
$ fastlane deliver
Localização cruzada: a App Store dos EUA indexa palavras-chave em inglês e espanhol. Localizar os metadados em espanhol capta pesquisas de utilizadores hispânicos nos EUA sem visar um mercado separado.
7

Testar a localização

Teste o conteúdo localizado sem alterar o idioma do dispositivo. Utilize substituições de esquema no Xcode para executar a aplicação em qualquer idioma, pré-visualizações SwiftUI com o ambiente regional e XCUITest com argumentos de arranque para testes automatizados.

Testing Localization
// 1. Xcode Scheme Override:
// Edit Scheme > Run > Options > App Language > Choose language

// 2. SwiftUI Preview with locale:
struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ContentView()
            .environment(\.locale, Locale(identifier: "de"))

        ContentView()
            .environment(\.locale, Locale(identifier: "ja"))

        ContentView()
            .environment(\.locale, Locale(identifier: "ar"))
    }
}

// 3. XCUITest with language override:
let app = XCUIApplication()
app.launchArguments += ["-AppleLanguages", "(de)"]
app.launchArguments += ["-AppleLocale", "de_DE"]
app.launch()
Teste com alemão —as cadeias aumentam cerca de 30% face ao inglês— e japonês —diminuem cerca de 50%— para detetar cedo problemas de disposição. Utilize a pseudolocalização do Xcode para submeter as disposições a testes exigentes sem traduções reais.

Automatizar a qualidade das traduções

Detete chaves em falta, marcadores danificados e problemas de plural antes da publicação com i18n-validate. Teste a interface com pseudotraduções através de i18n-pseudo antes de chegarem as traduções reais.
8

Automatizar as traduções

Traduza os seus ficheiros .strings, .xcstrings e de metadados do Fastlane com IA. Automatize a tradução das cadeias da aplicação e dos metadados da App Store para uma presença totalmente localizada.

Terminal
# Translate .strings files
> Translate Base.lproj/Localizable.strings
  to Japanese, German, and Spanish

# Translate App Store metadata too
> Translate fastlane/metadata/en-US/
  to de-DE, ja, es-MX

✓ 6 files translated in 3.2s
Uma presença localizada na App Store aumenta as transferências em mais de 30% nos mercados que não falam inglês. Traduza os metadados juntamente com as cadeias da aplicação: é a localização com maior retorno que pode fazer.
+

Extra: recurso regional inteligente com LocaleChain

Por predefinição, o iOS recorre ao idioma de desenvolvimento quando a região exata de um utilizador não está disponível. Um utilizador pt-BR com apenas traduções pt-PT vê inglês em vez de português. LocaleChain corrige isto com cadeias de recurso configuráveis.

LocaleChain é um pacote Swift de código aberto. Ver no GitHub

Package Dependencies
// Swift Package Manager
// File > Add Package Dependencies >
// https://github.com/i18n-agent/ios-localechain.git
MyApp.swift
import LocaleChain

// In your App init or AppDelegate:
LocaleChain.configure()  // Activates all default chains

// pt-BR user with only pt-PT translations?
// → Shows Portuguese instead of falling back to English

// Custom overrides for your specific locales:
LocaleChain.configure(
    overrides: ["es-MX": ["es-419", "es"]]
)

Erros frequentes

Erros de sintaxe no ficheiro .strings

A falta de pontos e vírgulas, aspas sem escape ou uma codificação incorreta provocam falhas silenciosas. O ficheiro é carregado, mas as traduções aparecem vazias. Valide sempre os ficheiros .strings antes de fazer commit.

A interpolação de Text no SwiftUI não é localizada

Text("Hello \(stringVar)") não é localizado como esperado. Utilize String(localized:) para cadeias calculadas ou certifique-se de que as variáveis interpoladas têm o tipo correto para LocalizedStringKey.StringInterpolation.

Os widgets e as extensões mostram chaves em bruto

As extensões da aplicação têm pacotes separados. Certifique-se de que os ficheiros .strings ou .xcstrings são adicionados à fase Copy Bundle Resources do destino da extensão, não apenas ao destino principal da aplicação.

As traduções em falta mostram chaves em produção

Quando uma chave não tem tradução no idioma do utilizador, o iOS mostra a própria chave. Utilize uma estratégia de idioma de recurso e teste todas as regiões compatíveis antes do lançamento.

Estrutura de ficheiros recomendada

Project Structure
MyApp/
├── MyApp.xcodeproj
├── MyApp/
│   ├── Base.lproj/
│   │   ├── Localizable.strings       # Source strings
│   │   └── Localizable.stringsdict   # Plural rules
│   ├── en.lproj/
│   │   └── Localizable.strings
│   ├── de.lproj/
│   │   └── Localizable.strings
│   ├── ja.lproj/
│   │   └── Localizable.strings
│   ├── Localizable.xcstrings          # OR String Catalog
│   └── Info.plist
├── MyAppTests/
├── fastlane/
│   ├── Fastfile
│   └── metadata/
│       ├── en-US/
│       │   ├── name.txt
│       │   ├── description.txt
│       │   └── keywords.txt
│       ├── de-DE/
│       └── ja/
└── Package.swift

Experimente já o i18n Agent

Largue aqui o seu ficheiro de tradução

JSON, YAML, PO, XML, CSV, Markdown, Properties

ou clique para selecionar

Idiomas de destino

Sem registoEstimativa imediata

Recurso regional com ios-localechain

Quando falta uma chave de tradução numa região como de-AT, o iOS passa diretamente para o idioma de desenvolvimento em vez de verificar primeiro a região principal de.

Terminal
// Swift Package Manager
// https://github.com/i18n-agent/ios-localechain
Configuration
import LocaleChain

LocaleChain.configure(overrides: [
    "de": ["en-GB", "en"],
    "pt-BR": ["pt", "en"],
    "zh-Hant-HK": ["zh-Hant", "zh", "en"],
])

Consulte o nosso guia de recurso regional para ver a lista completa de frameworks compatíveis e as 75 cadeias integradas. Learn more →

Perguntas frequentes sobre localização de iOS