Localize um app iOS
Traduza catálogos de strings da Apple ou recursos legados sem perder os idiomas compartilhados. Depois, verifique o resultado no Xcode e no app.
Um app iOS pode manter as mesmas chamadas de busca de textos localizados enquanto seus arquivos de recursos recebem um novo idioma. O Lingo.dev traduz esses recursos; o Xcode e o app continuam determinando qual pacote, tabela, idioma e variação o usuário vê.
Use o formato que o projeto já carrega. Os catálogos de strings reúnem vários idiomas em um único arquivo .xcstrings, enquanto os recursos .strings e .stringsdict usam arquivos separados por idioma. Essa diferença determina onde o resultado é gravado e o que precisa ser protegido durante uma atualização.
Defina quais recursos são a referência oficial #
Em um projeto com catálogos de strings, identifique o idioma de desenvolvimento, os idiomas de destino compatíveis e os catálogos carregados pelo app. O Xcode 15 introduziu o .xcstrings, geralmente chamado de Localizable.xcstrings. As mensagens podem ser distribuídas entre vários catálogos, por funcionalidade ou pacote; inclua todos os que fornecem textos à tela que você está localizando.
Para recursos legados, identifique os diretórios .lproj, as tabelas de strings e os dicionários de plural relevantes. Base.lproj pode conter recursos de interface de base; não presuma que sua presença, por si só, informa ao tradutor qual idioma de origem ou tabela de strings usar. Mantenha a configuração do idioma de desenvolvimento do projeto coerente com a configuração dos arquivos.
Antes de traduzir, vincule os textos da tela às chamadas de busca de textos localizados. A tradução de arquivos não substitui strings de interface fixas no código nem registra recursos em um destino do Xcode. Preserve os comentários que explicam aos revisores quem fala e em qual tela. O processador de catálogos de strings existente mantém esses comentários, mas não os inclui nas dicas das unidades de tradução. Por isso, insira o contexto necessário para a geração nas orientações aceitas pelo engine de localização.
Configure um catálogo de strings compartilhado #
Instale e vincule a versão atual da CLI a partir da raiz do projeto:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'App/Localizable.xcstrings' --yes
lingo linkPara um catálogo nesse caminho, o .lingo/config.json resultante deve ter esta estrutura:
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es", "fr"],
"files": [{ "pattern": "App/Localizable.xcstrings" }]
}Mantenha os identificadores gerados pela vinculação em vez de copiar os marcadores de posição. A extensão seleciona xcode-xcstrings. Cada destino grava no mesmo caminho do catálogo, adicionando entradas de idioma e preservando a origem e os demais idiomas. Um targetPath separado não é válido para esse formato de arquivo compartilhado.
O valor de origem fica dentro da estrutura compartilhada:
{
"sourceLanguage": "en",
"strings": {
"Welcome": {
"comment": "Greeting on the signed-in home screen",
"localizations": {
"en": { "stringUnit": { "state": "translated", "value": "Welcome" } }
}
}
},
"version": "1.0"
}Após a tradução, procure as entradas dos idiomas solicitados ao lado de en. O processador também aceita nós-folha de variações de plural e de dispositivo na origem e ignora entradas marcadas com shouldTranslate: false. Se uma entrada não tiver uma localização de origem, sua chave será usada como texto de origem; uma chave técnica não substitui a mensagem pretendida. Catálogos de strings da Apple explica essas regras de seleção e por que a origem atual e o catálogo existente precisam permanecer alinhados.
Mantenha os arquivos legados em caminhos próprios #
Em um projeto legado, use estas entradas de arquivo no lugar da entrada do catálogo compartilhado:
[{ "pattern": "App/en.lproj/Localizable.strings" }, { "pattern": "App/en.lproj/Localizable.stringsdict" }]Inclua apenas os recursos que realmente existem no projeto. As extensões selecionam os respectivos processadores; a saída em espanhol deve ficar em App/es.lproj/. Mantenha a configuração do idioma de desenvolvimento do projeto coerente com essa seleção de origem.
As chaves das strings e os marcadores de formatação fazem parte do contrato em tempo de execução. Preserve %@, os argumentos posicionais e os tipos esperados pelo código que faz a chamada. Um .stringsdict contém uma estrutura de variáveis de plural que deve permanecer coerente com sua string de formato. Consulte Strings da Apple e Dicionários de strings para conhecer os contratos específicos de cada formato, em vez de tratar qualquer um deles como XML ou texto arbitrário.
Traduza e inspecione o resultado mesclado #
Antes de substituir o catálogo atual, preserve-o no controle de versão ou em uma cópia separada. Para proteger as edições locais, envie sem --wait e inspecione lingo pull --dry-run antes de recuperar o resultado. Resolva as divergências em vez de forçar a sobrescrita. A gravação após a espera não faz a nova verificação de conflitos realizada na recuperação; consulte Preserve traduções revisadas.
Para uma primeira tradução sem conflitos, use o comando a seguir apenas se o catálogo permanecer inalterado durante a espera. Antes de adicionar idiomas a um projeto existente, conclua as atualizações normais da origem para os idiomas existentes, recupere e inspecione os resultados. Depois, mantenha essa revisão da origem fixa enquanto adiciona e preenche os novos idiomas. Adicione um idioma explica a ordem necessária:
lingo push --backfill-missing --waitOs catálogos compartilhados recebem planejamento por idioma, mesmo quando o arquivo já existe. Inspecione as entradas dos idiomas solicitados em vez de procurar um novo nome de arquivo. Um primeiro envio simples pode estabelecer a linha de base da origem sem traduzir. Após alterações normais na origem, use lingo push --wait; se não aguardar, recupere o resultado registrado com lingo pull no checkout usado para o envio.
Para corrigir a redação, edite a entrada de destino no Xcode. O --force da CLI ainda pode reutilizar traduções incorporadas em um catálogo inalterado. Para gerar novamente uma entrada após mudar as orientações, use o procedimento de correção do catálogo, que preserva a origem e as traduções vizinhas.
lingo purge ignora os catálogos de strings porque a origem e os destinos compartilham o mesmo caminho. Para gerar novamente uma tradução selecionada, use o workflow de correção de catálogos de strings.
Verifique no Xcode e em telas representativas #
Abra o resultado no Xcode e confira se o catálogo ou arquivo legado está incluído no destino e no pacote pretendidos. Compile usando o esquema existente do projeto. Execute uma configuração no idioma de destino e inspecione uma tela que contenha um rótulo simples, um valor formatado e uma variação de plural ou de dispositivo.
Compare os marcadores de posição do idioma de destino com o código que faz a chamada. Teste contagens que selecionem diferentes formas de plural em cada idioma; as categorias do inglês não são uma especificação completa para todos os idiomas de destino. Verifique se os idiomas não alterados continuam presentes no catálogo mesclado. Revise rótulos longos, textos de acessibilidade, truncamento e comportamento da direita para a esquerda, quando aplicável.
As verificações de compilação do Xcode podem detectar problemas nos recursos, enquanto um revisor linguístico ou uma medição aplicável verifica o significado. lingo check não comprova que .xcstrings está completo nem que os plurais da Apple funcionam corretamente.
Garanta que a automação preserve o arquivo compartilhado #
Mantenha os textos de origem, as traduções aceitas, a configuração e .lingo/lock.json juntos. Depois, escolha o GitHub App ou um executor de CI para o trabalho recorrente. O executor gerencia sua própria autenticação, seu estado e a gravação dos resultados para revisão. Revise as diferenças de um catálogo de strings como uma alteração em um arquivo compartilhado: identifique a revisão da origem, os idiomas alterados e os idiomas preservados antes de aceitar a alteração.
Para projetos multiplataforma, use os workflows separados de Android e Flutter para qualificadores XML e geração de ARB. Cada plataforma ainda precisa de suas próprias verificações de carregamento de recursos e de telas renderizadas.