Sessão prática de codificação: explore recursos de localização no Xcode

Olá! Sou Andreas, da equipe de localização. Nesta sessão vamos explorar a localização com o Xcode.

Aqui não é necessário conhecimento prévio. Vamos descobrir juntos como configurar um app para localização. Falaremos sobre fornecer o contexto certo para quem trabalha na tradução dos apps, entenderemos algumas das complexidades encontradas conforme o projeto cresce e abordaremos os novos recursos para ajudar a gerenciá-lo! Vamos começar.

Nesta sessão, escreveremos código juntos. Ou seja, você pode aplicar as etapas neste vídeo ao projeto de exemplo indicado na descrição. Baixe o projeto Landmarks e comece a localizá-lo comigo! O projeto está aberto no Xcode. Esta versão do Landmarks funciona bem em inglês, mas ainda não tem traduções. Vamos adicionar um String Catalog usando o menu File.

Podemos usar o nome padrão Localizable, mas quero que ele siga para Recursos. Aí também está o Asset Catalog. O String Catalog foi adicionado, então vamos compilar o projeto. Quando há um String Catalog, o Xcode descobre os caracteres localizáveis após cada compilação e as adiciona ao Catalog. Não há nada que precisemos fazer para sincronizar os caracteres no Catalog com o código. Mas como o Xcode sabe quais caracteres localizar? A API SwiftUI torna os caracteres localizáveis por padrão. Incluindo visualizações Text e Button. No restante, String(localized: ) também dispõe os caracteres para localização.

Vou usar o Assistant Editor para entender de onde os caracteres no String Catalog foram extraídos.

Isto vem de uma caixa de confirmação.

Aqui são caracteres usados no título de LabeledContent, esses no título de navegação. E esse vem de Text usando uma variável interpolada. A maior parte da API SwiftUI é localizável imediatamente. Você já deve ter notado que esses caracteres representam um número de itens. %lld é substituído pelo número de marcos em tempo de execução. Esses caracteres devem ser diferentes, dependendo desse número. Por exemplo, vamos expressar: 1 item e 2 itens.

Vamos abrir o menu de contexto e selecionar Vary by Plural.

Agora podemos escrever as frases para um item e vários itens.

Em tempo de execução, o sistema escolhe os caracteres certos. Foi uma solução fácil.

Localização tem tudo a ver com outros idiomas. Falo alemão. Então posso escrever algumas traduções sozinho direto no String Catalog. Fecharei o Assistant. Para adicionar um idioma, clico no botão de adição na barra inferior e seleciono German. Pronto, vou começar a adicionar algumas traduções.

Note que, o estado muda de NEW para TRANSLATED conforme avanço, indicado pelo marca de seleção verde à direita.

E também a porcentagem geral de tradução na barra lateral aumentou para 8%.

Sou melhor desenvolvedor que tradutor, então me juntei a um especialista em idiomas. Prefiro que ele termine as traduções para o alemão.

Para enviar o que tenho até agora, acesso o menu Product no Xcode e seleciono Export Localizations. Como traduzo o app para o alemão, vou exportar apenas o alemão.

Isso gera um arquivo de catálogo de localização com as traduções em alemão e os caracteres em inglês que ainda não foram traduzidos. O package-file contém um arquivo XLIFF padrão, com o qual os serviços de tradução trabalham facilmente. No final, eles enviarão de volta o catálogo de localização traduzido.

Para importá-lo para o projeto, vou ao menu Product e seleciono Import Localizations.

O Xcode cria o projeto e todos os caracteres são marcados como traduzidos, e German está em 100%. Experimente você! O projeto de exemplo contém o arquivo de.xcloc traduzido que você pode importar para o Xcode. Agora vamos testar, e eu gostaria de executar o app em alemão. Abro o editor de esquemas, edito o esquema, seleciono Run e acesso Options.

Podemos alterar o idioma do app para alemão para a próxima depuração.

Vou compilar e executar o app no Mac.

Totalmente localizado para o alemão. Gostei do visual!

É muito fácil configurar um novo app para localização. Vamos ver com mais detalhes como fornecer contexto adicional aos tradutores para garantir traduções de alta qualidade. O Assistant Editor no Xcode é fantástico para ver o código ao lado do String Catalog. Mas, em geral, os tradutores não veem o código ou o app em execução ao traduzir. Precisamos fornecer contexto adicional para ajudá-los a traduzir melhor.

O contexto vai em forma de comentário. No código ou na coluna para comentários do String Catalog. Sem comentário, fica difícil entender como os caracteres são usados. Por exemplo, Landmarks é uma única palavra. Isso é o nome do app ou pontos de referência em um mapa? Essa chave diz que %@ está contido em %@. Como os tradutores sabem o que %@ representa? Isso afeta a tradução! O comentário explica em que elemento da interface os caracteres aparecem, como barra de abas, botão ou subtítulo.

Também é útil descrever os elementos da interface circundantes. Por exemplo, indicar que os primeiros caracteres estão na barra lateral. Os caracteres seguintes são o subtítulo de um ponto de referência em uma lista. Por fim, um comentário deve explicar o conteúdo que aparece nos espaços reservados. Aqui, o primeiro é o nome de um ponto de referência e o segundo é o nome de um conjunto do qual ele faz parte. Sem um comentário, isso seria impossível de traduzir corretamente. Por isso, é fundamental fornecer um bom comentário!

No ano passado, os String Catalogs passaram a rastrear de onde os caracteres são extraídos. Este ano, essas informações vão ajudar você. Aqui está a geração de comentários no Xcode 26!

O Xcode usa um modelo no dispositivo para analisar código e agora escreve comentários. Vamos ver na prática. Até agora, fornecemos comentários para alguns caracteres no código. Depois de aprender sobre os comentários, vamos melhorar o contexto para os tradutores. Aqui temos caracteres sem comentários. Parece que é usado em um Button. Abro o menu de contexto e seleciono Generate Comment. Depois de analisar os caracteres, o Xcode gerou O rótulo em um botão para cancelar a exclusão de uma coleção. Preciso!

Esses aqui também não têm comentário ainda, vou deixar Xcode gerá-lo.

Ele criou Um rótulo abaixo do local de um ponto de referência. Muito bom. Mas ainda podemos fazer edições aqui. Sua entrada sempre substitui um comentário gerado. Trabalho junto com o modelo para fornecer contexto extra. Acrescento que esses caracteres aparecem no Inspector.

Esse recurso é muito útil e quero que o Xcode gere um comentário para todos os caracteres que extrair do código. Para ativar isso, abro Settings e acesso Editing.

Ativo o ajuste Automatically generate string catalog comments. Agora, quando o Xcode detectar caracteres localizáveis adicionados ao código, ele gerará o comentário automaticamente. Isso torna muito fácil fornecer o contexto que os tradutores precisam.

Para ajudar desenvolvedores de ferramentas de tradução a indicar um comentário gerado pelo Xcode, no XLIFF exportado aparece auto-generated.

Para saber mais sobre interoperabilidade com outras ferramentas e o que mais um String Catalog pode fazer, confira “Descobrir os String Catalogs”.

Conforme o projeto cresce e se torna mais complexo, há recursos adicionais do Xcode e das APIs de localização que ajudam na organização. Quando um projeto aumenta de tamanho e vários desenvolvedores começam a trabalhar nele, às vezes dividimos a base de código em extensões, frameworks e pacotes do Swift. E cada um deles pode conter um ou mais String Catalogs. Nesses casos, precisamos usar outro parâmetro na API de localização: bundle. Ele informa ao sistema o local dos caracteres em tempo de execução. 'Bundle.main' sempre se refere ao app principal. Se não incluirmos o parâmetro bundle, .main será usado por padrão.

A novidade agora é a macro #bundle. Você pode usá-la para referenciar o pacote que contém recursos do destino atual. Esse é o app principal, se o código for executado no app principal, ele encontrará automaticamente recursos do framework ou pacote do Swift. Ele também funciona em versões mais antigas do sistema operacional.

Outra maneira de organizar os caracteres é agrupar os relacionados, como em uma tela, um recurso ou fluxo de usuário específico. Chamamos grupos de caracteres de Table, e cada String Catalog representa uma tabela.

Todos os caracteres são extraídos para uma tabela Localizable. Ela corresponde ao nome de arquivo padrão se cria um String Catalog. Claro, podemos mudar o nome! O parâmetro tableName permite colocar caracteres no String Catalog. Usar o nome da tabela Discover os coloca em Discover.xcstrings.

Embora o app de Landmarks funcione bem ao criar coleções privadas de Landmarks, quero desenvolver um recurso para descobrir mais conteúdo. Esse conteúdo vem de amigos que eu sigo ou de um feed selecionado. Vamos desenvolver esse recurso em um novo framework.

Vou abrir o menu File e adicionar um novo Target. Vou procurar framework.

Como o framework é sobre descobrir novos marcos, vou chamá-lo de DiscoverKit.

Começo uma nova tela do zero e quero colocar todos os caracteres em uma tabela separada. Adiciono um arquivo ao DiscoverKit, seleciono String Catalog e chamo-o de Discover.

Abro o código no Editor do lado direito, mantendo pressionado Shift e Option enquanto clico no arquivo do Swift.

Ganho mais algum espaço fechando o Navigator.

Começo a desenvolver o recurso na camada de modelo com enum. O novo enum define se o conteúdo vem de um amigo ou é curadoria. Ele tem uma propriedade para expor um título localizado. Vamos usar. Começo usando String(localized: ) para expor os caracteres para localização. Usarei o argumento table para melhor organização. Como é um framework, preciso usar o argumento bundle também. E vamos fazer o mesmo no outro caso.

O enum está feito. Vou importar a SwiftUI e adicionar uma visualização para ver conteúdo na tela.

Não tenho lógicas de negócios em vigor. Então vou mostrar um espaço reservado que diz que haverá 42 novas publicações.

Chega de digitar, é hora de deixar o Xcode trabalhar! Mudo o esquema para o novo framework e compilo.

Assim que a compilação terminar, os caracteres aparecerão no Catalog.

E eles já têm um comentário! Legal!

Para o trabalho de interface restante, apresento um novo fluxo de trabalho no Xcode 26. Desde a introdução dos String Catalogs, eles têm ajudado na extração de caracteres do código. Mas agora, eles ajudam a escrever código gerando símbolos para caracteres adicionados manualmente. Continuamos a criar a visualização com o fluxo de trabalho. Pretendo adicionar um título e um subtítulo de navegação. Agora, a visualização está em desenvolvimento. Ao separar as chaves dos caracteres de seus valores, posso iterar o texto exato sem precisar atualizar o código.

Para começar, clico no botão + no String Catalog para adicionar os caracteres. Muitos projetos usam a configuração com chaves maiúsculas para indicar um significado semântico. Farei isso aqui. A chave deve ser TITLE, e o valor Discover Landmarks. Como adicionei os caracteres manualmente, escreverei o comentário.

O Attribute Inspector informa como usar os caracteres no código. Isso é muito útil! Vou fazer isso!

Para mostrar um título na barra de navegação, usarei .navigationTitle.

Para seu valor, digitarei um ponto à esquerda e o nome da tabela. O Xcode pode preencher automaticamente o nome da tabela e todas os caracteres manuais contidos na tabela.

Foi fácil! Nem precisei digitar manualmente um nome de pacote e tabela desta vez.

Vou fazer isso novamente para o subtítulo! Adiciono caracteres ao Catalog e chamo-o de SUBTITLE.

Quero resumir quantas postagens são de amigos e quantas foram selecionadas. Preciso de um espaço reservado e especificadores de formato. Começo digitando % e o Xcode me sugere alguns para usar. Quero um número e escolho um espaço reservado para um inteiro.

O espaço reservado friendsPosts representa o número de publicações de amigos.

Adiciono outro espaço reservado para postagens selecionadas.

É hora de um comentário.

Os caracteres estão prontos para o código. Vou usar o modificador Navigation Subtitle.

Começo a digitar .Discover para achar a tabela certa, e o preenchimento automático faz o resto.

Foi muito menos digitação! Observe como o Xcode sugeriu os tipos corretos. O novo recurso facilita o trabalho com caracteres manuais, e posso confiar no preenchimento automático e no compilador para carregar os recursos localizados. Quando eu quiser alterar os valores dos caracteres mais tarde, posso simplesmente atualizá-los no String Catalog sem ter que modificar o código. De quantas maneiras diferentes você já escreveu OK e queria corrigir todas com uma ação simples?

Para gerar um nome de símbolo perfeito no Swift, o Xcode usa a chave e o valor dos caracteres. Caracteres sem espaço reservado são acessados como propriedade estática. Se os caracteres têm um espaço reservado, o Xcode gera uma função e usa o nome do espaço reservado como rótulo de argumento. Os símbolos gerados são variáveis estáticas ou funções no tipo LocalizedStringResource. Isso é bom, porque você pode usá-los em qualquer lugar que se usa um LocalizedStringResource! Isso inclui views da SwiftUI, como Text ou Button, ou modificadores, como .navigationSubtitle() Se você não usa a SwiftUI, String(localized: ) também funciona com o tipo LocalizedStringResource.

Views personalizadas e outras declarações com LocalizedStringResource podem ser chamadas por um símbolo gerado.

Os símbolos estarão diretamente acessíveis em LocalizedStringResource se você usar Localizable. Ao usar um nome de tabela não padrão, os símbolos são aninhados no namespace. Você pode acessá-los em código começando com o nome da tabela. Os novos projetos criados pelo Xcode 26 têm a geração de símbolos ativada. Para usá-la, ative o ajuste de compilação Generate String Catalog Symbols.

O Xcode agora é compatível com dois fluxos de trabalho para gerenciar caracteres: extraí-los do código e referenciá-los com uma API type-safe. Isso levanta a questão: qual fluxo de trabalho uso? Recomendo que você comece com a extração de caracteres. Você escreve os caracteres onde desenvolve a interface, permitindo que você leia e entenda o código com rapidez. Nesse fluxo de trabalho, você usa a geração de comentários do Xcode, então você digita menos e fornece um bom contexto aos tradutores. À medida que o projeto cresce, você pode querer mais controle sobre a organização dos caracteres. Nesse caso, recomendamos o uso de símbolos gerados. Isso permite que você separe chaves de seus valores para iterar no texto sem alterar o código. O preenchimento automático do Xcode facilita a referência aos caracteres em todas as tabelas. Finalmente, os símbolos gerados ajudam a evitar o código clichê em frameworks e pacotes.

As duas abordagens têm seus pontos fortes, e você deve ser livre para decidir o que funciona melhor para o seu projeto. Por isso, adicionamos um recurso de refatoração para que você possa alternar facilmente entre as duas. Vamos experimentá-lo no framework DiscoverKit! O texto de espaço reservado dentro de Navigation Stack é um ótimo candidato para servir de referência a um símbolo. Abro o menu de contexto e seleciono Refactor > Convert Strings to Symbols.

Uma interface de prévia é aberta, mostrando os locais exatos onde o símbolo será usado em vez dos caracteres. Clicar na seção destacada me permite comparar o símbolo com o código original.

Vamos mudar o nome da chave para feedTitle para torná-la mais semântica. Posso adicionar um nome para Argument 1! Vou chamá-lo newPosts. Ficou bom! Vou confirmar a refatoração.

Pensei um pouco sobre as abordagens e decidi usar símbolos gerados para todos os caracteres na tabela. Vamos selecionar os dois restantes com Refactor > Convert Strings to Symbols.

Os nomes dos símbolos são bons. Vou clicar em Convert.

Assim é fácil refatorar uma tabela inteira de uma só vez. Recomendo que você explore os recursos de localização no Xcode. Comece confiando na extração de caracteres. Forneça comentários significativos aos tradutores, seja escrevendo você mesmo ou com a geração de comentários do Xcode. Conforme a complexidade do projeto aumentar, use os símbolos gerados para manter um controle preciso sobre os caracteres.

Finalmente, para saber mais sobre String Catalogs, confira o vídeo “Descobrir os String Catalogs”. Obrigado. Espero que os novos recursos ajudem a simplificar o fluxo de trabalho de localização.