Para concluir um rótulo pluralizado de um app para Mac, adicione variações de plural no Xcode, forneça todas as categorias necessárias para cada localização compatível e teste os resultados renderizados. Este passo a passo usa uma mensagem fictícia de seleção de itens.

A tarefa é concluir um único rótulo dependente de contagem em um app para Mac feito com SwiftUI. A mensagem informa quantos itens estão selecionados, aceita um número inteiro não negativo e preserva esse significado nas traduções. O fluxo de trabalho combina cobertura de categorias, verificações de marcadores de posição e testes em tempo de execução para que uma entrada preenchida no catálogo tenha critérios claros de aceitação.

O que é necessário para completar a cobertura de plurais?

A Apple recomenda os catálogos de strings para a localização de plurais no Xcode 15 e versões posteriores. A documentação de plurais distingue uma alternativa obrigatória da completude gramatical: other é obrigatório em um dicionário de strings, mas omitir categorias adicionais específicas do idioma pode resultar em gramática incorreta. O inglês exige one e other; a categoria zero é opcional. Localizar strings que contêm plurais.

Os nomes possíveis das categorias são zero, one, two, few, many e other. Eles descrevem agrupamentos gramaticais que dependem do idioma, e não seis intervalos numéricos compartilhados por todos os idiomas. Uma categoria chamada one não deve se tornar uma regra universal do app que verifica apenas se a contagem é igual a um. O Unicode define categorias com base nas alterações que os números exigem em uma frase, inclusive alterações que vão além do substantivo. Regras de plural.

Para esta tarefa, use o seguinte contrato de mensagem. Estes são requisitos ilustrativos do app, não requisitos impostos pela Apple.

Campo do contrato Requisito para este exemplo
Chave da mensagem selection.count
Valor padrão em inglês \(count) items selected
Entrada Um Int Swift não negativo chamado count
Significado Número de itens selecionados no momento
Saída Um rótulo localizado completo contendo a contagem
Cobertura Todas as localizações compatíveis, incluindo a localização de origem
Aceitação Categorias obrigatórias preenchidas, substituição numérica preservada, resultados representativos verificados

Exigir que o número apareça é uma escolha deliberada para este rótulo. A Apple permite variantes de plural que escrevem o número por extenso ou omitem o especificador de formato numérico. Um contrato de mensagem diferente poderia permitir isso. Aqui, manter a contagem visível facilita compará-la à seleção que ela descreve. Localizar strings que contêm plurais.

Vincule a mensagem Swift ao catálogo

String.LocalizationValue do Swift oferece suporte a texto localizável com interpolação em tempo de execução. Quando um identificador estável deve ser diferente do texto de origem em inglês, a Apple orienta os desenvolvedores a usar um inicializador de String com um defaultValue separado. Isso é adequado a selection.count: o identificador nomeia a mensagem, enquanto o valor padrão fornece o texto em inglês. String.LocalizationValue.

Para um app de teste pequeno, crie no Xcode 15 ou posterior um projeto de app para macOS usando SwiftUI, com destino de implantação no macOS 12 ou posterior. Substitua o arquivo de entrada gerado do app pelo programa completo abaixo; mantenha apenas uma declaração @main no destino. Adicione Localizable.xcstrings ao destino do app antes de seguir as etapas do catálogo. O programa requer o Xcode e o SDK do macOS; ele não foi compilado neste ambiente de pesquisa.

import Foundation
import SwiftUI

@main
struct PluralSampleApp: App {
    var body: some Scene {
        WindowGroup {
            PluralSampleView()
        }
    }
}

struct PluralSampleView: View {
    @State private var count: Int = 1

    private let samples: [Int] = [
        0, 1, 2, 3, 4, 5, 10, 11, 12,
        20, 21, 22, 100, 101, 102, 1_000_000
    ]

    private var selectionLabel: String {
        String(
            localized: "selection.count",
            defaultValue: "\(count) items selected",
            comment: "Selection summary. The integer is the number of selected items. Keep the count visible in every plural variant."
        )
    }

    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            Picker("Sample count", selection: $count) {
                ForEach(samples, id: \.self) { value in
                    Text(verbatim: String(value)).tag(value)
                }
            }

            Text(verbatim: selectionLabel)
        }
        .padding(24)
        .frame(minWidth: 360)
    }
}

As opções numéricas do seletor são entradas de teste. O resumo localizado é resolvido por String(localized:defaultValue:comment:) e, em seguida, exibido como a string resultante. A Apple documenta que o primeiro argumento do inicializador fornece a chave de busca, o valor padrão fornece o texto de origem e os comentários dão contexto para a tradução. O Xcode extrai strings passadas por APIs localizáveis durante uma compilação. Preparar o texto do app para tradução.

Mantenha o número inteiro dentro da interpolação localizável. Para este contrato, não crie previamente frases separadas em inglês para singular e plural usando ramificações no app. Manter uma única mensagem dá ao catálogo uma responsabilidade clara: selecionar a formulação localizada apropriada para a contagem fornecida.

Forneça as categorias para cada localização compatível

Use o editor do Xcode para criar a estrutura de variações:

  1. Escolha Product > Build para preencher o catálogo.
  2. Abra Localizable.xcstrings e selecione a localização de origem.
  3. Clique com o botão direito do mouse em selection.count e escolha Vary by Plural.
  4. Preencha cada variação do idioma de origem.
  5. Adicione localizações compatíveis usando o botão Add da barra lateral e preencha as variações.

O Xcode adiciona formas de plural específicas do idioma e determina o especificador de formato da interpolação. Aplicar a variação de plural à localização de origem mantém a estrutura de variações sincronizada entre os idiomas; aplicá-la somente a outra localização afeta apenas essa localização. Localizar e variar texto com um catálogo de strings.

Para esta interpolação de inteiro, as entradas em inglês podem ser:

Categoria em inglês Valor no catálogo
one %lld item selecionado
other %lld itens selecionados

Use o especificador que o Xcode gerar para o tipo real da interpolação. O exemplo de inteiro documentado pela Apple usa %lld; copiar um marcador de posição diferente para uma tradução pode quebrar o contrato do argumento. Inicialmente, o Xcode preenche os campos de variação com o valor da chave, então verifique a formulação em cada campo. Localizar e variar texto com um catálogo de strings.

Monte uma planilha de cobertura com uma linha para cada identificador de localização existente. Registre as categorias que o Xcode gera para esta mensagem, se cada uma tem texto finalizado e quais entradas você testará. Usar os identificadores reais do projeto impede que um rótulo amplo de idioma oculte uma localização que ainda não foi revisada.

Não copie o conjunto de categorias do inglês para todas as linhas. Da mesma forma, não exija as seis categorias em todos os casos. Deixe o catálogo fornecer a estrutura de trabalho e, em seguida, consulte as regras cardinais de plural do idioma ao selecionar entradas de teste. As regras cardinais dizem respeito a quantidades; as ordinais, a posições, e respondem a outra pergunta. O Unicode documenta esses tipos de regras separadamente. Unicode Technical Standard #35: Numbers.

Valide separadamente a estrutura, os marcadores de posição e o texto renderizado

Faça três verificações, pois cada uma responde a uma pergunta diferente. Uma categoria ausente é um problema de cobertura; um marcador de posição incorreto é um problema de formatação; uma frase estranha é um problema de redação. Registrar cada um separadamente deixa claro qual correção fazer em seguida.

Verifique a cobertura das categorias

Para cada linha da planilha, compare as categorias esperadas com as entradas preenchidas no catálogo. Confirme que other existe e que nenhuma categoria esperada tem um valor vazio ou uma cópia inacabada do texto de origem.

Para uma verificação simples de completude, defina o conjunto esperado como as categorias geradas para aquela localização mais qualquer substituição intencional compatível. O conjunto de ausências corresponde ao conjunto esperado menos as categorias que contêm texto finalizado. Qualquer item ausente deixa a mensagem inacabada segundo os critérios de aceitação deste artigo. Este é um método prático de revisão baseado no fluxo de trabalho de variações documentado, e não uma afirmação de que o Xcode impõe exatamente esta lista de verificação.

Se duas categorias tiverem legitimamente a mesma formulação, mantenha-a onde for necessário e revise ambas as entradas. O objetivo é preservar o significado da mensagem nas categorias obrigatórias; não é necessário que todas as strings sejam visivelmente diferentes entre si.

Verifique a substituição numérica

Compile e revise os diagnósticos do catálogo. A Apple documenta a validação de catálogos de strings para problemas comuns, como especificadores de formato incompatíveis. Resolva esses diagnósticos e, em seguida, verifique se cada variante ainda atende ao requisito desta mensagem de exibir a contagem. Criar apps prontos para vários idiomas.

Neste exemplo com um único argumento, verifique se o marcador de posição numérico está presente, continua sendo numérico e aparece uma vez no lugar pretendido. Uma compilação bem-sucedida é uma evidência útil, mas a decisão de aceitação também exige cobertura das categorias e texto realmente renderizado.

Teste contagens representativas no app para Mac

Escolha Product > Scheme > Edit Scheme, selecione Run e abra Options. Defina App Language e a App Region aplicável, feche a caixa de diálogo e execute o app para Mac. Repita para cada localização compatível. A Apple documenta este procedimento com esquemas para testar resultados localizados. Testar localizações ao executar o app.

O seletor de exemplo oferece um conjunto inicial de contagens, não uma cobertura universal de categorias. Adicione valores apropriados a cada localização antes de considerar completa a linha de teste correspondente.

Opção de teste O que verifica
0, 1 e 2 Seleções vazias, de um item e de poucos itens
Pelo menos uma entrada representativa por categoria obrigatória Cobertura das distinções gramaticais da localização
Valores em ambos os lados de limites relevantes das regras Mudanças de categoria além das contagens menores
Uma contagem válida alta Substituição numérica e espaço disponível para o rótulo
Cada entrada testada Significado, formulação completa e contagem visível

As regras do Unicode associam categorias a condições e exemplos de valores; detalhes numéricos, inclusive casas decimais, podem ser relevantes. Este contrato aceita apenas números inteiros. Se o app passar a aceitar quantidades decimais, revise em conjunto a interpolação, a formulação de origem e os testes, em vez de presumir que os resultados para inteiros continuam comprovando a cobertura. Unicode Technical Standard #35: Numbers.

Diagnostique um resultado inesperado

Use o sintoma observado para escolher o que inspecionar em seguida:

Sintoma Próxima ação
selection.count não está no catálogo Compile novamente e inspecione a chamada localizável e a tabela selecionada
Apenas uma localização tem variações de plural Confira novamente onde Vary by Plural foi aplicado
Uma variante ainda tem a formulação de plural em inglês Inspecione o campo preenchido previamente e forneça a tradução final
O número exibido está ausente ou malformado Compare o marcador de posição da variante com o especificador gerado pelo Xcode e o contrato da mensagem
Uma contagem maior usa uma formulação inesperada Verifique a regra de categorias dessa localização e adicione um teste representativo
A formulação correta não cabe Ajuste a visualização e teste novamente o rótulo completo

Em um projeto mais antigo que usa uma versão do Xcode anterior à 15, o caminho compatível da Apple usa recursos .strings e .stringsdict. O dicionário de plurais fornece variantes específicas do idioma e exige other; isso não elimina a necessidade de fornecer as demais categorias necessárias para a correção gramatical. Localizar strings que contêm plurais.

Conclua a mensagem quando cada localização compatível tiver uma linha de cobertura completa, seus marcadores de posição atenderem ao contrato e contagens representativas produzirem o rótulo pretendido no app em execução. Revise essas linhas sempre que as localizações compatíveis, o tipo de entrada numérica ou o significado da mensagem mudarem.

Fontes