Um comentário útil para tradutores explica o significado de uma etiqueta, onde ela aparece e o que acontece quando alguém a usa. Este guia mostra como escrever e anexar esses comentários no Xcode para um navegador simples de formas para Mac, usando etiquetas sintéticas em inglês.

O que um comentário para tradutores deve explicar?

Comece pela decisão que o tradutor precisa tomar. Uma etiqueta curta como Round não deixa claro seu papel gramatical nem o significado pretendido. Um comentário pode identificá-la como um adjetivo que descreve uma categoria de formas e explicar que ela aparece acima de um grupo de pré-visualizações. A Apple recomenda comentários que esclareçam onde e como uma string é usada na interface. Descubra os catálogos de strings

Para quem está preparando as etiquetas de um app para Mac para tradução, a tarefa concreta é transformar cada string ambígua em uma explicação breve e independente. O tradutor deve conseguir entender sua finalidade sem navegar pelo código-fonte.

Use este roteiro de escrita em quatro partes. É um método editorial derivado das orientações da Apple, não um formato de comentário exigido pela Apple:

Parte Pergunta a responder Detalhe de exemplo
Significado A que se refere o texto original? Round descreve formas com contornos curvos.
Função na interface Que tipo de texto da interface é este? Um título de categoria acima das pré-visualizações das formas.
Comportamento ou localização O que acontece ou o que aparece ao redor? Expand revela detalhes abaixo da pré-visualização.
Conteúdo variável O que cada valor inserido pode conter? O primeiro valor é o nome de uma forma; o segundo é o nome de uma coleção.

Inclua apenas as partes que afetam a interpretação. Um título estático não precisa de explicação sobre uma ação. Um botão se beneficia de uma descrição clara do que acontece quando alguém toca nele. Uma mensagem com dois nomes inseridos precisa explicar a relação entre eles.

A Apple recomenda especificamente explicar o elemento da interface, os elementos ao redor e o conteúdo representado pelos marcadores de posição. Trate esses detalhes como contexto prático para a tradução. Acompanhamento de código: explore a localização com o Xcode

Transforme comentários vagos em descrições úteis das mensagens

Os exemplos a seguir pertencem a um navegador ilustrativo de formas para Mac. Cada comentário aprimorado descreve um comportamento explícito presumido da interface; adapte esse comportamento ao controle real antes de usar o texto.

Etiqueta original Comentário fraco Comentário mais útil
Shapes Etiqueta para formas. Item de navegação da barra lateral que abre a lista de formas geométricas. Substantivo no plural.
Round Texto de forma. Título de categoria acima das pré-visualizações de formas com contornos curvos. Adjetivo que descreve as formas.
Expand Título do botão. Botão abaixo da pré-visualização de uma forma que revela seus detalhes abaixo da pré-visualização. Verbo que expressa uma ação.
Selected Etiqueta de seleção. Status ao lado da forma selecionada no momento para a pré-visualização. Descreve o estado atual da forma.

As versões fracas repetem o que o tradutor já consegue ver. As versões melhores fornecem as relações que faltam: qual objeto o adjetivo descreve, qual conteúdo o botão revela ou qual item está em determinado estado.

Em inglês, um substantivo nomeia algo, um adjetivo descreve algo e um verbo no imperativo indica uma ação. Essas distinções ajudam a explicar textos compactos de interface. Por exemplo, Selected nesta ilustração descreve um estado existente; Select em um botão pediria uma ação. Indique qual interpretação a interface exige.

Mantenha os comentários concretos. Para Expand, explique se o controle revela um texto de detalhes, amplia uma pré-visualização ou abre um grupo na barra lateral. Nomear a operação é mais útil do que dizer que ela aumenta algo.

Evite impor regras desnecessárias de formatação em inglês. Se a interface precisa de um título de categoria conciso, diga isso. Não invente um limite fixo de caracteres nem exija que a tradução preserve a ordem das palavras em inglês. Documente uma restrição real de layout somente quando souber que ela se aplica.

Adicione comentários para tradutores no SwiftUI

A Apple documenta o parâmetro comment: de Text como uma forma de incluir dicas de tradução. Quando o inicializador conveniente de uma string de um controle não oferece o comentário necessário, use o construtor de conteúdo com uma view Text explícita. A Apple demonstra esse padrão para Label e explica que muitos controles do SwiftUI são compatíveis com ele. Prepare as views para localização

O exemplo completo abaixo é um pequeno app SwiftUI para macOS. No Xcode, crie um projeto de app para macOS usando SwiftUI, defina o destino de implantação como macOS 13 ou posterior e substitua o código gerado do app e da view de conteúdo por este único arquivo. Mantenha apenas um ponto de entrada do app. O exemplo usa nomes sintéticos fixos e revela uma frase de detalhes quando o usuário toca em Expand.

import SwiftUI

@main
struct ShapeCommentDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ShapeBrowserView()
        }
    }
}

struct ShapeBrowserView: View {
    @State private var showsDetails = false

    private let shapeName = "Circle A"
    private let collectionName = "Shape Set A"

    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            Text(
                "Round",
                comment: "Category heading above previews of shapes with curved outlines. Adjective describing the shapes."
            )
            .font(.headline)

            Circle()
                .fill(Color.blue)
                .frame(width: 80, height: 80)

            Text(
                "\(shapeName) in \(collectionName)",
                comment: "Caption below a shape preview. The first value is the shape name; the second is the collection containing it. Sample names: Circle A and Shape Set A."
            )

            Button {
                showsDetails = true
            } label: {
                Text(
                    "Expand",
                    comment: "Button below a shape preview that reveals its details beneath the preview. Verb expressing an action."
                )
            }
            .disabled(showsDetails)

            if showsDetails {
                Text(
                    "A shape with a curved outline.",
                    comment: "Detail sentence revealed below the preview after clicking Expand. Describes the displayed circle."
                )
            }
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 300)
    }
}

Este exemplo foi inspecionado conforme os padrões de API documentados; ele não foi compilado nem executado aqui porque o ambiente disponível não tem uma toolchain Swift.

Para strings voltadas ao usuário criadas fora de uma view do SwiftUI, a Apple documenta String(localized:comment:). Use o argumento de comentário da API de localização para anexar o contexto à mensagem. A Apple também oferece suporte a uma chave de busca e a um valor de origem padrão separados, quando eles precisam ser diferentes. Prepare o texto do seu app para tradução

Explique os valores inseridos pelo significado e pela relação entre eles

A legenda do exemplo contém duas interpolações do Swift: \(shapeName) e \(collectionName). A interpolação do Swift insere os valores de expressões em uma string literal. Os nomes das variáveis pertencem ao código-fonte; a explicação ainda deve fazer sentido para alguém que não consegue ver esses nomes. Strings e caracteres

Para os valores sintéticos mostrados, a legenda em inglês é Circle A in Shape Set A. O comentário explica tanto a ordem dos valores inseridos quanto a relação entre eles: um nomeia a forma e o outro, a coleção que a contém. Isso fornece informações mais úteis do que simplesmente descrever dois argumentos de string.

Ao revisar uma mensagem interpolada, faça três perguntas:

  1. Que tipo de conteúdo pode aparecer em cada posição: um nome, uma contagem ou outro tipo de valor?
  2. Como os valores se relacionam entre si?
  3. O comentário continua correto para todos os valores que o app pode fornecer?

Identifique claramente os exemplos como amostras. Aqui, Circle A e Shape Set A ilustram as funções dos argumentos. Eles não definem uma tradução obrigatória nem uma lista completa de nomes possíveis.

As contagens exigem uma decisão de implementação separada. Se você adicionar mais tarde uma legenda como 3 shapes, um comentário pode explicar o que está sendo contado, mas as variantes gramaticais pertencem ao catálogo. A Apple documenta o uso de Vary by Plural para contagens interpoladas, incluindo formas separadas em inglês, como 1 item e 2 items. Localize e varie o texto com um catálogo de strings

Encontre e inspecione os comentários no Xcode

Para vincular os comentários no código ao catálogo, siga o fluxo de trabalho documentado pela Apple:

  1. Escolha File > New > File from Template.
  2. Filtre por string, selecione String Catalog em Resource e crie-o com o nome padrão Localizable.
  3. Escolha Product > Build para extrair as strings localizáveis.
  4. Selecione Localizable.xcstrings no navegador do projeto.
  5. Escolha Editor > Assistant e, em seguida, selecione uma chave para inspecionar sua origem ao lado do catálogo. Localize e varie o texto com um catálogo de strings

Confira se o comentário do catálogo corresponde ao uso real. No exemplo, Round deve explicar um título de categoria e Expand deve descrever a exibição de detalhes. Se uma string estiver faltando, confira se o código usa uma API localizável e se Use Compiler to Extract Swift Strings está ativado. A Apple identifica essa configuração de compilação como necessária para a extração de strings Swift baseada no compilador. Descubra os catálogos de strings

A Apple também oferece suporte à edição direta do contexto na coluna de comentários do catálogo de strings. A geração automática de comentários foi introduzida no Xcode 26; a documentação atual descreve como clicar em uma chave com a tecla Control pressionada e escolher Generate Comment. Se essa opção não estiver disponível na sua configuração, anexe um comentário no código ou insira-o no catálogo. Acompanhamento de código: explore a localização com o Xcode, Localize e varie o texto com um catálogo de strings

Revise o texto gerado em relação ao comportamento da interface. Uma descrição que identifica corretamente um botão ainda pode precisar esclarecer o objeto ou o resultado. Neste exemplo, a distinção útil é que Expand revela uma frase de detalhes abaixo da pré-visualização.

Decida se duas etiquetas idênticas podem compartilhar o mesmo contexto

A grafia igual em inglês não significa que o sentido também seja igual. Suponha que outra tela use Round como uma ação que arredonda um valor numérico. Combinar esse uso com o título da categoria de formas faria com que uma entrada do catálogo descrevesse duas funções gramaticais diferentes.

A Apple explica que uma string localizável tem uma chave de busca e pertence a uma tabela; as chaves são únicas dentro de cada tabela. A documentação do Swift da Apple também oferece uma forma compatível de usar uma chave distinta com um valor de origem padrão. Use chaves separadas quando os significados exigirem traduções independentes, mesmo que os valores exibidos em inglês sejam iguais. Descubra os catálogos de strings, Prepare o texto do seu app para tradução

Uma regra prática para decidir é perguntar se um único comentário consegue explicar todos os usos corretamente. Se o significado e a função na interface permanecerem consistentes, compartilhar o contexto pode ser adequado. Se a explicação precisar descrever operações sem relação entre si, reconsidere a estrutura das chaves. Essa é uma inferência de projeto baseada no modelo de chaves e tabelas da Apple, não uma regra que exija uma string própria para cada controle.

Antes de entregar uma etiqueta, leia o comentário sem consultar o código-fonte. Ele deve permitir que o tradutor identifique o significado pretendido, localize conceitualmente o texto na interface e entenda qualquer conteúdo inserido. Revise o comentário sempre que o comportamento ou a função da etiqueta mudar, para que a explicação continue descrevendo a interface que o usuário vê.

Fontes