Para renomear uma chave do catálogo de strings no Xcode, preserve a mensagem de origem separadamente, atualize as referências no código e verifique todas as traduções e variantes existentes. Para strings extraídas, o Xcode 26 oferece uma refatoração de conversão; alterar apenas uma chave de consulta não é suficiente.

Este guia é para quem mantém um app para Mac em SwiftUI com um catálogo .xcstrings existente. A tarefa é substituir chaves que correspondem ao texto das mensagens por identificadores significativos, mantendo intactas as palavras exibidas e as traduções. A Apple documenta as APIs e o fluxo de conversão abaixo, mas não garante que uma edição arbitrária de chave transfira automaticamente todas as traduções.

O que deve permanecer inalterado quando uma chave muda?

Uma mensagem localizável tem mais do que um identificador. A Apple descreve a chave, o valor padrão, o comentário e a tabela de strings como componentes separados. A chave identifica a mensagem em tempo de execução; o valor padrão fornece o texto de origem. Um catálogo contém as traduções e os metadados de uma tabela. Trate a renomeação como uma alteração coordenada do contrato dessa mensagem. Descubra os catálogos de strings

Antes de editar, registre o seguinte para cada entrada afetada. Estes exemplos sintéticos ilustram uma renomeação; não são resultados medidos.

Componente Antes Resultado pretendido
Chave de consulta Open collection collection.open
Mensagem de origem Open collection Inalterada
Tabela Localizable Inalterada
Pacote Pacote principal do app Inalterado
Contexto para tradutores Botão que abre a coleção selecionada Preservado
Traduções existentes Valores atuais em cada localização Preservadas
Argumentos de contagem, se houver Contagem inteira Mesmo tipo e significado
Variantes de plural ou dispositivo Ramificações existentes Preservadas

Use este registro para ajudar na comparação. Uma compilação bem-sucedida, por si só, não comprova que as traduções foram preservadas: o app ainda pode exibir uma mensagem padrão quando uma consulta não encontra correspondência. A documentação do SwiftUI explica que uma chave localizável pode ser exibida diretamente quando não há correspondência no catálogo. Com uma chave semântica, isso pode fazer com que um identificador como collection.open apareça na interface. Preparando as visualizações para localização

Encontre a origem antes de editar o catálogo

Abra o catálogo existente no navegador de projetos do Xcode. Selecione Editor > Assistant e, em seguida, selecione a entrada para inspecionar sua origem. A Apple também documenta a seta ao lado de uma chave e os exemplos de uso no inspetor Attributes como formas de localizar referências. Para strings extraídas, selecione Product > Build depois de alterar o código-fonte para sincronizar o catálogo. Localização e variação de texto com um catálogo de strings

Verifique se a entrada é extraída do código ou gerenciada manualmente. A Apple explica que o código-fonte controla as mensagens extraídas: as compilações sincronizam os valores de origem. Uma entrada traduzida que deixa de ser extraída permanece como Stale; uma entrada sem tradução pode ser removida. Entradas gerenciadas manualmente não são atualizadas nem removidas pela extração. Portanto, não exclua uma entrada antiga traduzida só porque apareceu uma substituta. Descubra os catálogos de strings

Crie um ponto de verificação recuperável antes de prosseguir e, depois, compare com ele a entrada afetada. Mantenha a tabela e o pacote inalterados durante esta tarefa para reduzir as possíveis causas de uma tradução ausente. As APIs de localização da Apple aceitam informações sobre a tabela e o pacote justamente porque elas determinam onde uma mensagem é encontrada. Preparando o texto do app para tradução

Use a refatoração de conversão do Xcode para strings extraídas

Em um projeto que usa o Xcode 26 ou posterior, considere converter a entrada extraída existente em um símbolo localizável gerado. A Apple introduziu esse fluxo no Xcode 26 e demonstra a alteração de uma chave para um nome semântico durante a conversão. Esta é uma forma documentada de alterar em conjunto a identificação e as referências de uma mensagem. Tutorial prático: explore a localização com o Xcode

  1. Nos ajustes de compilação, verifique se Generate String Catalog Symbols está definido como Yes, caso o projeto existente precise dessa opção ativada.
  2. No editor do catálogo, selecione a chave existente, clique nela com a tecla Control pressionada e escolha Refactor > Convert Strings to Symbols.
  3. Inspecione a prévia que mostra a alteração da chave no catálogo e os locais afetados no código-fonte.
  4. Edite o nome semântico proposto e, quando aplicável, os nomes dos argumentos na interface de conversão.
  5. Compare o código atual com o modificado usando a prévia destacada e clique em Convert.
  6. Compile e compare a entrada resultante com seu ponto de verificação, incluindo traduções e variantes.

A Apple documenta esses controles de conversão e mostra exemplos de uso gerado no inspetor Attributes. Use esses exemplos em vez de tentar adivinhar um identificador Swift a partir da pontuação na chave desejada do catálogo. Os símbolos gerados dependem das informações do catálogo, e tabelas que não sejam a padrão introduzem um namespace de tabela. Usando símbolos localizáveis gerados no código

Esta refatoração é especificamente uma transição de strings extraídas para símbolos gerados. A documentação citada não estabelece uma operação universal de renomeação para toda entrada gerenciada manualmente nem para toda referência externa. Se a prévia omitir uma referência necessária, trate-a explicitamente antes de remover a chave anterior.

Mantenha a extração se preferir chaves e valores padrão no código

Você também pode manter a extração controlada pelo código. A Apple oferece suporte explícito a chaves de consulta e mensagens de origem separadas por meio de String(localized:defaultValue:...): o primeiro argumento fornece a chave, e defaultValue fornece a string de origem. Por exemplo, uma chave semântica pode manter Open collection como mensagem padrão. Preparando o texto do app para tradução

O código-fonte completo a seguir demonstra esse padrão com um rótulo estático e uma contagem inteira. Use um destino de app SwiftUI para macOS com destino de implantação macOS 12 ou posterior e substitua o código-fonte de entrada do app existente, em vez de adicionar uma segunda declaração @main. Adicione Localizable.xcstrings ao destino do app. O exemplo foi inspecionado em relação às APIs da Apple; ele não foi compilado aqui porque não havia um conjunto de ferramentas Swift disponível.

import Foundation
import SwiftUI

@main
struct CatalogRenameDemoApp: App {
    var body: some Scene {
        WindowGroup {
            CatalogRenameDemoView()
        }
    }
}

struct CatalogRenameDemoView: View {
    private let itemCount: Int = 7

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(verbatim: String(
                localized: "collection.open",
                defaultValue: "Open collection",
                comment: "Label for opening the selected collection."
            ))

            Text(verbatim: String(
                localized: "collection.itemCount",
                defaultValue: "\(itemCount) items",
                comment: "Number of items in the selected collection."
            ))
        }
        .padding()
    }
}

Aqui, String(localized:...) resolve o texto localizado antes de exibir a string resultante. Text(verbatim:) torna essa etapa de exibição explícita. A Apple distingue a localização imediata de strings de LocalizedStringResource, que representa uma consulta que pode ser adiada. Para interfaces reutilizáveis que passam mensagens não resolvidas entre visualizações, a Apple recomenda um tipo localizável como LocalizedStringResource. LocalizedStringResource, Preparando o texto do app para tradução

Ao migrar uma mensagem existente com esta abordagem, compile para criar ou atualizar a entrada de destino e, em seguida, transfira as traduções existentes antes de excluir a entrada anterior. A Apple documenta como inserir traduções diretamente: selecione uma localização e edite a coluna do idioma correspondente. Para uma mensagem com variantes, preserve cada ramificação relevante em vez de copiar apenas o texto de nível superior. Esta transferência em etapas é um procedimento prático de migração derivado das ferramentas de edição documentadas, não uma garantia de renomeação automática. Localização e variação de texto com um catálogo de strings

Qual é a diferença entre extração e formatação em tempo de execução?

A extração acontece durante o desenvolvimento: o Xcode descobre as expressões localizáveis compatíveis e atualiza o catálogo. A formatação em tempo de execução ocorre quando o app resolve a mensagem e insere os valores. A contagem do exemplo 7 é um argumento em tempo de execução; ela não deve fazer parte da chave estável.

Mantenha a interpolação do inteiro dentro da expressão localizável. String.LocalizationValue, da Apple, oferece suporte à interpolação e orienta os desenvolvedores que desejam identificadores arbitrários a usar inicializadores com uma chave estática e um defaultValue separado. Construir primeiro uma string comum já formatada não equivale a preservar essa mensagem localizável e seus argumentos. String.LocalizationValue

Para mensagens de contagem com regras gramaticais, selecione a entrada de contagem extraída, clique nela com a tecla Control pressionada e escolha Vary by Plural. Complete as variantes da origem e as variantes obrigatórias de cada localização existente. Para uma origem em inglês, a Apple ilustra One com %lld item e Other com %lld items. Apenas adicionar a interpolação não completa essas variantes. Localização e variação de texto com um catálogo de strings

Durante uma renomeação, preserve os tipos, as posições e os significados dos argumentos. Se a mensagem antiga contiver uma contagem inteira, substituí-la por uma string pré-formatada também altera o contrato de formatação. Para símbolos gerados, o Xcode cria funções com parâmetros tipados para mensagens que contêm especificadores de formato; inspecione essas assinaturas durante a conversão. Usando símbolos localizáveis gerados no código

Verifique a preservação antes de remover a entrada antiga

Use as verificações a seguir para confirmar a conclusão. Elas ajudam a distinguir um problema no catálogo de um problema na consulta ou na formatação.

Verificação Resultado esperado Investigue se falhar
Texto de origem Corresponde ao ponto de verificação Valor padrão ausente ou alterado
Traduções existentes Todos os valores anteriores permanecem disponíveis sob a nova chave Transferência incompleta ou destino incorreto
Estrutura das variantes Todas as ramificações de plural e dispositivo anteriores permanecem Apenas um valor de nível superior foi copiado
Rótulo em tempo de execução Exibe a mensagem pretendida Incompatibilidade de chave, tabela, pacote ou localização
Contagens sintéticas 0, 1, 7 Os valores são inseridos corretamente e as ramificações obrigatórias de plural funcionam Incompatibilidade de argumento ou variante
Referências antigas Não resta nenhum uso necessário Migração incompleta

Para testar o app para Mac em uma localização existente, selecione Product > Scheme > Edit Scheme, escolha Run, abra Options e escolha um App Language. Feche a caixa de diálogo e execute o destino para Mac. Repita para as localizações afetadas pela renomeação, verificando o rótulo e a mensagem de contagem reais. A Apple documenta esse fluxo de teste baseado em esquemas. Testando localizações ao executar o app

Se a nova chave aparecer, mas sua tradução estiver vazia, volte à entrada anterior e transfira o conteúdo ausente. Se o identificador aparecer na tela, inspecione os dados da consulta. Se apenas as contagens falharem, inspecione a interpolação e as variantes. Remova a entrada antiga depois que o conteúdo tiver sido contabilizado e as referências necessárias tiverem sido atualizadas. A alteração concluída deve modificar o identificador e preservar a mensagem, seus argumentos e as traduções que os leitores já recebem.

Fontes