Para validar os espaços reservados de uma tradução no Mac, compare a posição, o tipo e o uso previsto de cada argumento com a mensagem de origem. Use os diagnósticos de incompatibilidade do Xcode, depois inspecione as substituições de plural e teste o rótulo renderizado com valores de exemplo distintos.

Este guia é para quem está revisando os rótulos localizados de um app para Mac no Xcode. A tarefa é conferir uma mensagem e suas traduções em relação aos valores fornecidos pelo app. Todos os rótulos abaixo são exemplos sintéticos em inglês; eles ilustram mecanismos de formatação, não traduções reais.

O que faz parte do contrato de argumentos de uma mensagem?

Um contrato de argumentos é um registro de revisão que descreve os valores recebidos por uma mensagem: suas posições, tipos de formatação, significados e usos esperados. É uma lista prática de verificação derivada do código-fonte e do catálogo, não um formato de arquivo separado da Apple.

String.LocalizationValue do Swift oferece suporte a strings localizáveis com valores de execução interpolados. A documentação também distingue o uso do texto de origem como chave de localização do fornecimento de uma chave separada e de um valor padrão. Por isso, um identificador sozinho pode não revelar os argumentos da mensagem: inspecione o texto de origem padrão e o ponto em que ele é chamado. String.LocalizationValue

Considere a string de formato Added %lld items to %@. Neste exemplo, o app fornece uma contagem inteira seguida pelo rótulo de uma coleção representada por um objeto. Anote o contrato antes de editar a tradução:

Posição do argumento Significado Formato esperado Valor ilustrativo
1 Número de itens adicionados %lld 7
2 Rótulo da coleção de destino %@ Canvas

A referência de formatos da Apple define %@ como uma conversão de objeto, %d como um inteiro assinado de 32 bits, %f como uma conversão de double e ll como o modificador de comprimento inteiro para long long. Ela também documenta formatos posicionais, como %1$@. Preserve todas as informações de tipo; trocar %lld por %d altera o tipo inteiro esperado. A referência está arquivada, então consulte-a para a sintaxe de formatos junto com a documentação atual dos catálogos. Especificadores de formato de string

Inclua os significados dos argumentos no registro de revisão, mesmo quando os tipos forem idênticos. Em Moved %@ to %@, uma verificação de tipos não consegue distinguir o rótulo do item do rótulo de destino. A sintaxe correta ainda precisa manter a relação correta entre os valores e as palavras.

Como encontrar a fonte oficial no Xcode?

Comece com o projeto aberto no Xcode e identifique o catálogo que contém a mensagem. Se a fonte tiver mudado, escolha Product > Build para atualizar as strings extraídas. Selecione o catálogo no navegador do projeto, escolha Editor > Assistant e selecione a chave da mensagem para ver sua fonte. A Apple documenta esse fluxo de trabalho para localizar e atualizar entradas do catálogo. Localizar e variar texto com um catálogo de strings

Confira quais valores o ponto de chamada realmente fornece, em que ordem e por qual API de localização. A Apple recomenda APIs localizáveis, como String(localized:); um inicializador com defaultValue separado usa o primeiro parâmetro como chave e o segundo como string de origem padrão. Isso é importante quando um identificador neutro, como collection.added.summary, corresponde à mensagem. Preparar o texto do app para tradução

Registre três coisas em conjunto: o catálogo e a chave, o texto de origem padrão e os significados e tipos ordenados dos argumentos. Se houver divergências, resolva-as antes de ajustar as traduções. Caso contrário, você pode fazer uma tradução corresponder a uma fonte desatualizada, em vez de às entradas atuais do app.

Forneça contexto também para edições futuras. A Apple permite adicionar comentários às strings localizáveis para explicar seu uso. Um comentário sintético útil diria que o argumento 1 é a contagem de itens e o argumento 2 é o rótulo da coleção de destino. Isso oferece ao tradutor informações que um especificador de formato não consegue expressar. Preparar o texto do app para tradução

Como verificar contagens, tipos e posições dos argumentos?

A Apple introduziu a validação de catálogos de strings para problemas comuns, incluindo incompatibilidades nos especificadores de formato, com correções disponíveis para alguns casos. Inspecione todos os diagnósticos apresentados pelo Xcode para a entrada. Trate qualquer correção sugerida como uma proposta de ajuste da sintaxe e verifique se ela preserva o significado da mensagem. Criar apps preparados para vários idiomas

Para uma mensagem simples sem substituições de plural, siga esta sequência de revisão:

  1. Identifique cada espaço reservado que consome um argumento no texto de origem e no texto candidato.
  2. Associe cada espaço reservado à posição do argumento correspondente.
  3. Compare o tipo de formato completo com o contrato.
  4. Confira se cada valor obrigatório aparece onde o texto espera encontrá-lo.
  5. Investigue individualmente as referências adicionadas, omitidas ou repetidas.

A notação posicional permite que uma tradução altere a ordem das palavras, mantendo a identidade dos argumentos. Em %2$@: added %1$lld items, o primeiro espaço reservado visível faz referência ao argumento 2, e o segundo faz referência ao argumento 1. A Apple documenta a sintaxe posicional n$. Especificadores de formato de string

A tabela de decisão a seguir aplica-se ao contrato ilustrativo de dois argumentos acima. Estes são resultados de revisão propostos, não resultados da execução do Xcode:

Texto candidato Resultado da revisão Motivo
Added %lld items to %@ Corresponde ao contrato simples Primeiro a contagem, depois o destino
%2$@: added %1$lld items Corresponde após a reordenação As posições explícitas preservam a identidade dos dois argumentos
Added %d items to %@ Corrigir o tipo inteiro O argumento 1 não usa mais o modificador de comprimento esperado
Added %lld items Investigar a omissão Falta o destino exigido por esta mensagem
Added %1$lld items to %1$@ Corrigir as referências O argumento 1 é referenciado com tipos incompatíveis; o argumento 2 está ausente
Added %1$lld items to %2$@ (%2$@) Revisar a repetição Há três ocorrências, mas apenas dois argumentos distintos referenciados

Mantenha separadas a contagem de ocorrências e a contagem de argumentos distintos. A última linha demonstra essa diferença de propósito: repetir o argumento 2 não cria um terceiro valor fornecido. Decidir se essa repetição cabe no texto é uma questão editorial. Para esta tarefa, sinalize-a até que sua finalidade seja esclarecida.

Da mesma forma, não conte todo caractere de porcentagem como um argumento. A Apple define %% como um sinal de porcentagem literal. Um rótulo de formato como Scale: %lld%% contém um espaço reservado de valor e um sinal de porcentagem escapado. Especificadores de formato de string

Por que as substituições de plural precisam de uma verificação diferente?

As mensagens com plural exigem a revisão tanto do mecanismo de seleção quanto do texto que exibe um valor. Na apresentação sobre catálogos de strings, a Apple explica que as substituições podem conter dicionários de casos de plural. O inspetor mostra a posição e o especificador de formato no estilo C do argumento de controle. Portanto, uma substituição pode depender de um argumento mesmo quando um ramo específico não o exibe numericamente. Conheça os catálogos de strings

Para uma mensagem sintética de contagem de itens, compare One item added com %lld items added. O primeiro ramo escreve a quantidade por extenso; o segundo a exibe. Uma regra que exigisse a mesma quantidade de espaços reservados visíveis em todos os ramos rejeitaria o primeiro sem necessidade. O comportamento documentado pela Apple para dicionários stringsdict permite explicitamente omitir o especificador de formato numérico nas formas de plural e dá como opção escrever o número por extenso. Formato de arquivo stringsdict

Use esta revisão que considera cada ramo:

  • Verifique a posição e o tipo do argumento de controle da substituição no inspetor.
  • Inspecione cada ramo de plural presente para a localização de destino.
  • Confira cada espaço reservado exibido em relação ao argumento ao qual faz referência.
  • Explique qualquer omissão da exibição numérica com base no texto do ramo.
  • Confira separadamente os demais argumentos da mensagem; escrever a contagem por extenso não explica a ausência de um rótulo de coleção.

Para duas contagens que variam de forma independente, preserve seus papéis separados. Uma mensagem sintética sobre itens e coleções precisa usar a contagem de itens para controlar a substituição de itens e a contagem de coleções para controlar a substituição de coleções. A Apple documenta várias substituições em uma única mensagem e explica que a saída em tempo de execução combina os casos de plural selecionados. Conheça os catálogos de strings

Como confirmar a mensagem corrigida no Mac?

Depois de corrigir a entrada, compile o app e inspecione os diagnósticos restantes do catálogo. Em seguida, execute a tela relevante na localização de destino. O fluxo de trabalho compatível com a documentação da Apple é escolher Product > Scheme > Edit Scheme, selecionar Run, abrir Options, escolher App Language e o App Region apropriado, clicar em Close e executar o destino selecionado. Testar localizações ao executar o app

Escolha valores de exemplo que tornem visíveis as trocas. Para dois argumentos de contagem, use números diferentes, como 2 e 7. Para dois argumentos de texto, use rótulos distintos, como Tile e Canvas. Estas são entradas de teste ilustrativas: o objetivo é revelar qual valor fornecido aparece em cada parte da mensagem.

Para mensagens com plural, teste valores que alcancem os ramos em análise. Quando duas substituições variarem de forma independente, inclua combinações que alterem uma contagem enquanto mantêm a outra fixa. Inspecione tanto o texto selecionado quanto a posição de cada valor exibido. Uma renderização bem-sucedida de uma combinação deixa os demais ramos sem verificação.

Mantenha o estado da tradução separado da verificação do contrato. A Apple descreve a marca de seleção verde do catálogo como o estado de traduzido depois que o texto foi inserido. Registre as verificações que realmente fez — mapeamento dos argumentos, comparação de tipos, inspeção dos ramos e exemplos renderizados — em vez de tratar esse indicador de estado como prova das quatro. Localizar e variar texto com um catálogo de strings

A mensagem está pronta para avançar quando seus espaços reservados correspondem aos argumentos fornecidos pretendidos, os tipos correspondem e qualquer omissão ou repetição específica de um ramo tem uma explicação clara. Manter esse contrato conciso junto à mensagem facilita avaliar a próxima edição da fonte ou da tradução.

Fontes