No Xcode 26 e versões posteriores, os catálogos de strings podem gerar acessores Swift que substituem chaves de localização digitadas manualmente. Este guia migra o resumo de seleção de um pequeno app para Mac para propriedades e funções tipadas e, em seguida, verifica o que o compilador realmente protege.

A tarefa é intencionalmente restrita: exibir o título de uma janela e um resumo contendo duas contagens inteiras. Todos os rótulos e valores são sintéticos. Você criará o contrato do catálogo, o conectará ao SwiftUI e verificará tanto os diagnósticos do compilador quanto o resultado visível.

O que faz um acessor de localização ser verificado em tempo de compilação?

A Apple introduziu a geração nativa de símbolos de catálogos de strings no Xcode 26. Uma entrada sem espaços reservados produz uma propriedade estática; uma entrada com espaços reservados produz uma função com parâmetros tipados. Ambas retornam LocalizedStringResource. Projetos novos do Xcode 26 ativam a geração por padrão; talvez seja necessário ativar a configuração de build em projetos existentes. Acompanhe a prática: explore a localização com o Xcode

A mudança útil ocorre no ponto de chamada. Um literal de string pode conter uma chave de busca sem fazer referência a uma declaração Swift. Um acessor gerado faz referência a um membro que precisa existir, e uma função gerada exige argumentos compatíveis com sua assinatura. A consequência prática desses mecanismos documentados é que um membro com erro de digitação ou um argumento incompatível gera um erro do compilador.

Essa proteção tem um escopo específico. O Swift pode verificar se o acessor existe e se os argumentos são compatíveis. Ele não pode determinar se a redação descreve a interface pretendida nem se dois argumentos inteiros válidos representam as contagens corretas. Trate os acessores como uma interface de programação verificada para suas mensagens.

Configure um pequeno app para Mac e seu contrato de mensagens

Use o Xcode 26 ou posterior e um destino de app SwiftUI para macOS. Neste exemplo, defina o destino de implantação como macOS 15 ou posterior. O tipo subjacente LocalizedStringResource está disponível a partir do macOS 13; o destino mais recente do exemplo é uma escolha de pré-requisito, não a versão mínima desse tipo. Um recurso representa texto localizável cuja busca pode ser adiada até que seja necessário. LocalizedStringResource

Adicione um catálogo por meio de File > New > File from Template. Selecione String Catalog em Resource, nomeie-o Workbench e inclua-o no destino do app. A Apple documenta que cada catálogo representa uma tabela; usar uma tabela separada aqui mantém juntas as duas mensagens do exemplo. Localizar e variar texto com um catálogo de strings

No editor do projeto, abra Build Settings, filtre por Generate String e defina Generate String Catalog Symbols como Yes para a configuração efetiva do destino. Essa é a opção documentada para projetos mais antigos. Usar símbolos localizáveis gerados no código

Selecione a localização de origem em inglês em Workbench.xcstrings. Adicione estas duas entradas usando o botão + da barra de ferramentas do editor do catálogo. Os comentários definem o significado das mensagens, incluindo as funções de seus argumentos.

Chave Valor de origem em inglês Comentário
TITLE Selection overview Título acima do resumo da seleção.
SUBTITLE %1$(selectedCount)lld selected; %2$(availableCount)lld available Resumo da seleção. selectedCount é o número de itens selecionados; availableCount é o número total de itens disponíveis, incluindo os selecionados.

Para SUBTITLE, você pode inserir cada espaço reservado pelo menu de preenchimento automático do Xcode: digite %, escolha o espaço reservado de inteiro e nomeie-o selectedCount ou availableCount. A Apple documenta variáveis nomeadas e parâmetros gerados para esses especificadores de formato. Selecione cada entrada e inspecione Generate Swift Symbol e Example Usages no inspetor de atributos. Usar símbolos localizáveis gerados no código

O contrato pretendido é uma propriedade para o título e uma função para o subtítulo que aceita dois valores Int. Confira a grafia gerada no inspetor antes de continuar: a Apple informa que os nomes dos símbolos usam tanto a chave quanto seu valor. Os exemplos abaixo usam .Workbench.title e .Workbench.subtitle(selectedCount:availableCount:), seguindo o padrão documentado pela Apple para chaves em maiúsculas. Acompanhe a prática: explore a localização com o Xcode

Esse contrato explicita uma distinção útil: availableCount inclui os itens selecionados. Sem esse comentário, quem chamar o acessor poderia interpretar, com razão, que o valor indica a quantidade restante. Ambas as interpretações passariam pela verificação de tipos, portanto documentar o significado faz parte de tornar o acessor útil.

Use os acessores gerados em uma janela completa

Depois de criar o catálogo, escolha Product > Build. Substitua a declaração do app de modelo e a visualização de conteúdo pelo programa a seguir, mantendo exatamente uma declaração @main no destino. O catálogo é um recurso necessário para este programa; colar o Swift em um arquivo independente não gera seus acessores.

import Foundation
import SwiftUI

@main
struct SelectionOverviewApp: App {
    var body: some Scene {
        WindowGroup {
            SelectionOverviewView(
                selectedCount: 3,
                availableCount: 12
            )
        }
    }
}

struct SelectionOverviewView: View {
    let selectedCount: Int
    let availableCount: Int

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(.Workbench.title)
                .font(.title2)

            Text(
                .Workbench.subtitle(
                    selectedCount: selectedCount,
                    availableCount: availableCount
                )
            )
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 140)
    }
}

Com a localização de origem em inglês ativa, as entradas ilustrativas devem exibir Selection overview, seguido de 3 selecionados; 12 disponíveis. As contagens são fixas para que você possa verificar a posição dos argumentos sem introduzir código de gerenciamento da seleção.

A Apple documenta que os recursos gerados podem ser usados no SwiftUI, inclusive com Text, e por meio do inicializador String(localized:) do Foundation. Se uma interface existente para Mac exigir uma String resolvida, converta o recurso gerado nesse ponto. Acompanhe a prática: explore a localização com o Xcode

Por exemplo, esta é uma função auxiliar completa que você pode adicionar ao mesmo destino do app depois que o catálogo existir:

import Foundation

func selectionSummary(
    selectedCount: Int,
    availableCount: Int
) -> String {
    String(
        localized: .Workbench.subtitle(
            selectedCount: selectedCount,
            availableCount: availableCount
        )
    )
}

Retornar LocalizedStringResource da sua própria interface preserva um recurso para uma busca posterior; retornar String resolve o recurso quando o inicializador é executado. Escolha com base no que a interface receptora precisa. A Apple descreve essa distinção entre busca adiada e imediata na documentação do Foundation. LocalizedStringResource

Os exemplos foram conferidos com base na documentação consultada. Eles não foram compilados aqui porque o ambiente disponível não tem um executável Swift nem o Xcode.

Por que o ponto inicial e os rótulos dos argumentos são importantes

O ponto inicial é a sintaxe de membro implícito do Swift. Ele abrevia o acesso a um membro de tipo quando o contexto ao redor permite que o Swift infira o tipo. É sintaxe comum do Swift, não um operador especial para chaves de string. Expressões — expressão de membro implícito

Nos símbolos de localização gerados, a tabela padrão Localizable expõe os membros diretamente, enquanto uma tabela nomeada introduz um espaço de nomes para a tabela. Por isso, este exemplo inclui .Workbench antes do nome do membro. A Apple documenta ambas as formas. Usar símbolos localizáveis gerados no código

Os rótulos selectedCount: e availableCount: pertencem à chamada da função. O Swift distingue rótulos de argumentos, que aparecem no ponto de chamada, dos nomes dos parâmetros usados dentro de uma função. Quando um parâmetro exige um rótulo, quem chama a função precisa fornecê-lo. Funções — rótulos de argumentos e nomes de parâmetros de funções

Rótulos claros ajudam a evitar erros, mas os dois argumentos têm o mesmo tipo. Trocar os dois valores inteiros continua sendo válido em Swift. Portanto, o contrato da mensagem e a verificação do resultado visível complementam o compilador.

Migre chaves existentes sem perder seu significado

Para strings localizáveis existentes, a Apple oferece um fluxo de trabalho de refatoração. Selecione as entradas no catálogo de strings, clique nelas com o botão direito enquanto mantém Control pressionado e escolha Refactor > Convert Strings to Symbols. Inspecione a prévia, ajuste os nomes propostos para símbolos ou parâmetros, se necessário, e escolha Convert. Usar símbolos localizáveis gerados no código

Comece migrando um grupo coeso, como o título e o resumo desta janela. Antes de aceitar a prévia, compare a mensagem antiga com o novo contrato: eles usam a mesma tabela, descrevem o mesmo elemento da interface e atribuem o mesmo significado a cada espaço reservado? Revise todos os valores localizados existentes afetados por uma mudança de chave, em vez de presumir que a refatoração comprova sua correção.

Para um ponto de chamada que a refatoração não atualizou, consulte o uso gerado no inspetor do catálogo e substitua essa referência explicitamente. Em seguida, compile e inspecione o texto resultante. Evite excluir a entrada antiga antes de verificar se ainda há chamadas que a usam.

Se a versão instalada do Xcode não tiver geração nativa, esse fluxo de trabalho exige uma cadeia de ferramentas mais recente. A Apple também permite extrair strings de APIs localizáveis para catálogos e recomenda a extração como ponto de partida. Essa continua sendo uma forma compatível de gerenciar a localização, mas, por si só, não oferece o contrato de acessores gerados descrito aqui. Acompanhe a prática: explore a localização com o Xcode

Verifique a migração com uma pequena sequência de diagnósticos

Faça as seguintes verificações na janela de exemplo. Elas separam a proteção do compilador da correção das mensagens e da integração dos recursos.

  1. Compile o exemplo sem alterações para estabelecer uma referência funcional.
  2. Altere temporariamente a grafia do membro do título e compile. O membro inexistente deve gerar um diagnóstico do compilador. Restaure a grafia.
  3. Passe temporariamente um valor String onde o subtítulo exige um Int. Compile para verificar a incompatibilidade de tipos e, em seguida, restaure o inteiro.
  4. Execute com selectedCount definido como 3 e availableCount definido como 12. Confirme que os números aparecem nas posições pretendidas.
  5. Altere apenas o valor do título no catálogo para Current selection, recompile e confirme o título exibido. Verifique se a assinatura gerada continua sendo a usada pelo código.

Se um membro estiver ausente inesperadamente, primeiro inspecione o uso gerado da entrada do catálogo. Depois, confira a configuração de geração, a inclusão do catálogo no destino e o nome da tabela. Um diagnóstico do compilador identifica uma referência inválida; essas verificações ajudam a distinguir um erro de grafia de uma declaração gerada indisponível.

Por fim, teste a interface real. O caminho documentado pela Apple é Product > Scheme > Edit Scheme e, em seguida, Run > Options, onde você pode selecionar App Language antes de executar. Repita o processo para as localizações compatíveis com seu projeto. Testar localizações ao executar o app

Para verificar o layout no início do processo, o Xcode também oferece Double-Length Pseudolanguage, que expande o texto localizável para revelar problemas de dimensionamento. Inspecione o resumo com a janela estreita; uma compilação bem-sucedida não garante que o texto caiba. Testar localizações

Uma migração concluída oferece a cada ponto de chamada um membro Swift real, atribui a cada variável uma função documentada e mantém um caminho verificado até a entrada pretendida do catálogo. Mantenha juntas as verificações do compilador e da janela: as primeiras validam o contrato do acessor, enquanto as últimas confirmam que as pessoas veem a mensagem pretendida.

Fontes