Para remover chaves de localização não utilizadas no Xcode, trate as entradas Stale como candidatas à revisão. Verifique a construção de chaves em tempo de execução antes de excluí-las, preserve as mensagens dinâmicas necessárias como entradas gerenciadas manualmente e teste as telas afetadas do app para Mac após a limpeza.

Este guia é para um desenvolvedor que mantém um app para Mac em SwiftUI com catálogos de strings. A tarefa é limpar um catálogo: identificar mensagens que podem ser removidas, preservando os rótulos e as mensagens com contagem que o app ainda exibe. O guia de decisão abaixo separa as evidências de extração do comportamento em tempo de execução.

O que uma chave de localização obsoleta realmente significa?

O Xcode descobre strings localizáveis durante as compilações. A Apple explica que a extração abrange o esquema e a plataforma atuais. Quando uma string extraída anteriormente desaparece, o Xcode pode remover automaticamente uma entrada sem tradução; uma entrada que tenha traduções permanece e recebe o estado Stale. Esse estado significa que o Xcode não encontra mais a string no código. A Apple deixa explícito que a exclusão depende de confirmar que a string não é mais necessária. Descobrir catálogos de strings

Na prática, a ausência de uma referência no código inicia uma investigação. Uma busca exata por panel.compact pode encontrar uma referência literal, mas não permite determinar se o código constrói essa chave combinando panel. com um modo selecionado. Revise tanto a chave candidata quanto o código que gera as chaves de consulta.

Use esta tabela de revisão proposta para cada candidata. Ela é um guia de decisão derivado dos limites de extração documentados, não um recurso adicional do Xcode.

Evidência encontrada durante a revisão Decisão Próxima ação
Uma tela removida era a única consumidora; não resta nenhum gerador de chaves em tempo de execução Excluir candidata Remova a entrada, depois recompile e confira a alteração
O código em tempo de execução ainda pode gerar exatamente esta chave Manter Preserve-a por gerenciamento manual ou substitua a consulta por referências localizáveis explícitas
A chave ainda é referenciada em outro destino ou condição de compilação Manter Compile e inspecione a configuração relevante
Existe uma chave com nome semelhante em outra tabela Investigar separadamente Confirme a tabela e o pacote de recursos usados por cada consulta
Nenhuma consumidora foi encontrada, mas o código que gera a chave não está claro Adiar Rastreie o gerador antes de decidir pela exclusão

Como estabelecer uma linha de base útil no Xcode?

Primeiro, salve uma cópia recuperável do catálogo ou faça commit do estado atual. Depois, abra o projeto do app e selecione o esquema para Mac que pretende revisar. Registre quais destinos e configurações condicionais podem fornecer mensagens à interface afetada; assim, a revisão fica vinculada a um escopo explícito.

Selecione o catálogo no navegador do projeto e escolha Product > Build. A Apple documenta que as compilações preenchem e atualizam os catálogos de strings com base no texto localizável do código-fonte. Com o catálogo selecionado, escolha Editor > Assistant e selecione uma chave para inspecionar sua localização no código-fonte. O catálogo também permite navegar de volta ao código-fonte. Localizar e variar texto com um catálogo de strings

Se as strings Swift esperadas estiverem ausentes, verifique se a configuração de compilação Use Compiler to Extract Swift Strings está ativada para o destino. A Apple documenta esse pré-requisito para a extração pelo compilador. Um catálogo preenchido com uma extração incompleta não é uma boa linha de base para decidir o que remover. Localize seu app em SwiftUI

Para cada candidata, registre a chave, o catálogo, a possível consumidora e a decisão. Primeiro, busque a chave exata; depois, o prefixo estável e os wrappers de localização relevantes. Inspecione os valores do modelo e os dados de consulta incluídos no pacote que alimentam esses wrappers. Repita as compilações relevantes quando outro destino ou condição de compilação alterar o código-fonte incluído.

Não agrupe decisões só porque duas entradas exibem o mesmo texto. As APIs de localização da Apple aceitam nomes de tabelas, e recursos fora do app principal podem exigir outro pacote. Rastreie a tabela e o pacote da consulta antes de tratar outra entrada como substituta. Preparar o texto do app para tradução

Como preservar mensagens referenciadas dinamicamente?

A Apple documenta o gerenciamento manual especificamente para strings cujas chaves são construídas dinamicamente. Selecione a entrada necessária e use o inspetor para defini-la como gerenciada manualmente. Essas entradas não são atualizadas nem removidas pela sincronização de localização do Xcode após a compilação. Para uma entrada dinâmica ausente, a Apple também demonstra como adicionar uma string manual usando o botão de adição do catálogo. Descobrir catálogos de strings

O gerenciamento manual exige uma regra explícita de manutenção. Registre as chaves válidas junto ao código ou aos dados que as selecionam e explique seu uso nos comentários do catálogo. Se um modo compatível for removido mais tarde, revise também a entrada manual correspondente; a extração automática não fará essa limpeza por você.

Verifique se o SwiftUI realmente faz uma consulta

Uma variável String passada para Text é exibida sem localização. Para usar uma variável como chave de consulta, a Apple documenta criar uma LocalizedStringKey a partir dela. Um literal passado diretamente para Text segue automaticamente o caminho localizável. Essas sobrecargas podem produzir o mesmo resultado no idioma de origem, embora se comportem de formas diferentes. LocalizedStringKey

O app de demonstração completo a seguir mantém uma chave selecionada em tempo de execução separada de uma contagem interpolada. Em um projeto SwiftUI descartável para Mac, usando o Xcode 15 ou posterior e um destino de implantação macOS 13, substitua a declaração de app gerada por este código. Mantenha apenas uma declaração @main. O código foi inspecionado com base nas APIs documentadas; não foi compilado aqui porque não havia uma cadeia de ferramentas Swift disponível.

import SwiftUI

@main
struct CatalogReviewDemoApp: App {
    var body: some Scene {
        WindowGroup {
            CatalogReviewView()
        }
    }
}

struct CatalogReviewView: View {
    @State private var compact = true
    @State private var itemCount = 2

    private var selectedKey: String {
        "panel." + (compact ? "compact" : "expanded")
    }

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Toggle("Compact layout", isOn: $compact)

            Text(LocalizedStringKey(selectedKey))

            Text("\(itemCount) items",
                 comment: "Number of items in the sample panel.")

            Button("Add item") {
                itemCount += 1
            }
        }
        .padding()
        .frame(minWidth: 320)
    }
}

Adicione Localizable.xcstrings ao destino do app. Adicione entradas gerenciadas manualmente para panel.compact e panel.expanded, com os valores de origem Compact panel e Expanded panel. Compile o projeto para extrair as mensagens literais. A conversão explícita para LocalizedStringKey solicita uma consulta em tempo de execução; ela não fornece ao extrator uma declaração literal de cada chave construída possível.

Para um conjunto pequeno e finito de opções, considere substituir a construção de chaves por literais localizáveis explícitos em cada ramificação. Para interfaces personalizadas que passam mensagens entre componentes, a Apple recomenda LocalizedStringResource, que carrega informações de localização, como tabela, comentário e valor padrão. Escolha a representação que facilite inspecionar o conjunto completo de mensagens compatíveis. Preparar o texto do app para tradução

Por que contagens variáveis são diferentes de chaves variáveis?

Na demonstração, selecionar um layout altera qual chave de mensagem o app consulta. Alterar itemCount fornece um argumento diferente a uma mensagem localizável. A interpolação do SwiftUI converte os valores embutidos em marcadores de formato para localização; a renderização em tempo de execução fornece os valores. Localize seu app em SwiftUI

Portanto, você não precisa de chaves separadas para os rótulos renderizados 2 items, 3 items e 4 items. Compile o exemplo, localize a mensagem de contagem extraída, clique com a tecla Control na chave e escolha Vary by Plural. Para uma localização de origem em inglês, informe %lld item para One e %lld items para Other, usando o marcador inteiro exibido pelo Xcode. A Apple documenta esse fluxo de trabalho para mensagens com contagem e a adição das variantes de plural adequadas a outras localizações compatíveis. Localizar e variar texto com um catálogo de strings

Durante a limpeza, inspecione uma mensagem com contagem como um recurso completo, incluindo suas variações. A ausência no código-fonte de uma expressão renderizada como 4 items não diz nada sobre o uso da mensagem interpolada subjacente. Da mesma forma, manter um modelo de contagem não preserva uma chave dinâmica sem relação só porque ambas as mensagens aparecem no mesmo painel.

Quais entradas uma limpeza deve realmente remover?

Considere uma revisão ilustrativa de 24 candidatas. Essas quantidades descrevem um exemplo sintético, não um resultado medido em um projeto.

Resultado da revisão Entradas Ação
As únicas consumidoras pertenciam a um painel removido 9 Excluir após confirmar que o painel e seus dados de consulta foram removidos
As chaves continuam acessíveis por seleção em tempo de execução 8 Manter e documentar o gerenciamento manual
As referências pertencem a outro destino ou a uma compilação condicional 5 Manter e verificar esse escopo de compilação
A origem da chave continua sem solução 2 Manter enquanto se investiga
Total revisado 24 9 candidatas à exclusão

Este cálculo torna a decisão de limpeza auditável: 24 entradas revisadas não significam 24 exclusões. Para cada uma das nove candidatas à exclusão, registre uma justificativa breve que identifique a consumidora removida e os caminhos de consulta em tempo de execução verificados. Para as oito entradas dinâmicas, registre o conjunto de chaves permitidas para que a próxima revisão possa repetir a decisão.

Remova apenas as candidatas confirmadas e, depois, inspecione as diferenças do catálogo. Confira se a alteração contém as chaves pretendidas e suas traduções associadas, sem que variantes de plural ou de dispositivo sem relação desapareçam. Recompile as configurações relevantes. Se uma chave excluída voltar a aparecer por meio da extração, investigue novamente a consumidora antes de excluí-la outra vez.

Como verificar as mensagens mantidas no Mac?

Use Product > Scheme > Edit Scheme, selecione Run e abra Options. Escolha uma localização compatível existente em App Language, feche o editor e execute o destino para Mac. A Apple documenta esses controles de esquema para testar compilações localizadas. Repita para as localizações compatíveis com o app. Testar localizações ao executar o app

Exercite cada seleção dinâmica permitida, incluindo os dois layouts da demonstração. Confirme que o app exibe os valores esperados do catálogo, em vez dos identificadores. Para mensagens com contagem, confira valores de teste como 0, 1, 2 e 12, e verifique categorias adicionais de plural quando as localizações compatíveis exigirem isso. Basta alterar a contagem inicial do exemplo para chegar a esses valores de teste.

Quando uma mensagem mantida for exibida incorretamente, inspecione a chave exata, a tabela, o pacote e o inicializador Text antes de alterar o catálogo. O fluxo de geração de símbolos mais recente da Apple também pode facilitar o uso de recursos manuais: o Xcode 26 introduziu a geração de símbolos de catálogos de strings, ativada em projetos existentes pela configuração Generate String Catalog Symbols. Este é um caminho opcional de refatoração, não uma evidência de que um recurso manual sem referência esteja sem uso. Programação guiada: explorar a localização com o Xcode

Conclua com um pequeno conjunto de exclusões justificáveis e uma lista documentada das mensagens dinâmicas mantidas. O resultado útil é um catálogo cujas entradas restantes tenham consumidoras identificáveis, enquanto as chaves selecionadas em tempo de execução e as mensagens de contagem formatadas continuam funcionando na interface do Mac.

Fontes